Re: [Hamlib-developer] Documentation plan

[Stephane F. <f4...@fr...>]

On Wed, Jan 03, 2001, Nate Bargmann wrote:
> Okay, I've been going over things the past day or so and would like to
> get started by creating an introductory homepage for hamlib.  Some
> things I'd like to include are an overview of the library's purpose and
> its implementation.  After that is in place I'd like to expand that by

  Excellent idea!
  List of supported features (planed or future ones from the whish list)
  might have its place here. see PLAN file (from CVS, or tarball),
  which is rather coder scratch notes, almost human readable :)

> documenting the version 1.1.0 API.  As this becomes complete it should

  The problem with API documentation is doco isn't updated when
  code changes. That's why hamlib have hamlib-doc, a clone from kernel-do=
c,
  which is actually a clone of gnome-doc, ...., a clone of java-doc, etc.
  Ok, the fact is it's in doc/ directory, and API calls are documented
  in the source file, mainly src/rig.c
  Output can be done in html, text, anything (sgml/docbook), and man page=
s.
  For the man pages, you will have to split them with:

	./hamlib-doc -man ../src/rig.c  | ./split-man.pl man

  Even if you're not a core coder, you can still document the code,
  ask question if something looks obscure to you (it might be obscure=20
  to someone else, and even to the coder who forgot his ugly tricks :).

> probably be included in the next stable release.  Far into the future
> come things like HOWTO guides and radio command indexes and such.
>=20
  sounds a good plan to me. http://hamlib.sourceforge.net is as much need=
ed
  as code!

  Here's an ugly gizmos, that leave plenty of space for improvements,
  I named rigmatrix. This is a combined list/dump program, that creates
  a table of supported radios in HTML format, with dynamically generated
  PNG pics for the rx/tx ranges (thanks to GD lib).
  Not fancy stuff yet, but at least you got the meat :)=20
  If you want a different format and don't know how to change the code,
  just ask me (a sample of the output you'd like will help).
  You can check it out at the following URL:
                http://f4cfe.free.fr/ham/hamlib/rigmatrix.html


> Is there a preferred style for the web pages?  I don't plan on using
> frames or a lot of fancy gizmos.
>=20
  Something simple will do, to begin with. I like the style
  of the Linux IEEE1394 project. The URL should be something like
  http://ieee1394.sourceforge.net  (I'm offline line right now)

  Very import too, I think we need a logo. You know, like a small
  picture to identify Hamlib. I have no good ideas yet.=20
  This can be a simple PNG showing a rig linked to a computer.
  Or this can be a serial cable, ala Icom (however Hamlib is not
  serial specific, it will run on network connections, and others)
  This might be also a cute animal, like a kangaroo, recalling
  a certain country (Did you remember the google.com during=20
  the Olympics games?). Do you have any other idea ?
  Artists and gimp experts, this is time to show off!

> Finally, I installed the ssh (OpenSSH) 1.2.3-9.1 debian package
> yesterday, but cannot log into hamlib.sourceforge.net as the Sourceforg=
e
> documentation indicates.  Is this reserved for the project owner, or is
> there some other reason (Frank?).  Or will I need to contact Sourceforg=
e
> to get this resolved?
>=20
  nope, the ssh has a different name, something like ssh1.sourceforge.net
  or shell1.sourceforge.net. Have a look at the SSH FAQ on sourceforge,
  it's well explained.
  Unless you have a good low-latency ISP service, I'd recommend you
  to work offline and then use cvs update/commit or scp.

  Anyay, It's good to see the Hamlib team growing!


Have fun,

--=20
St=E9phane