hamlib-developer

[Hamlib-developer] Documentation plan

[Nate B. <n0...@ne...>]

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
documenting the version 1.1.0 API.  As this becomes complete it should
probably be included in the next stable release.  Far into the future
come things like HOWTO guides and radio command indexes and such.

Is there a preferred style for the web pages?  I don't plan on using
frames or a lot of fancy gizmos.

Finally, I installed the ssh (OpenSSH) 1.2.3-9.1 debian package
yesterday, but cannot log into hamlib.sourceforge.net as the Sourceforge
documentation indicates.  Is this reserved for the project owner, or is
there some other reason (Frank?).  Or will I need to contact Sourceforge
to get this resolved?

73, de Nate >>

-- 
 Wireless | Amateur Radio Station N0NB          | "None can love freedom
 Internet | n0...@ne...               | heartily, but good
 Location | Wichita, Kansas USA EM17hs          | men; the rest love not
   Wichita area exams; ham radio; Linux info @  | freedom, but license."
             http://www.qsl.net/n0nb/           | -- John Milton

Re: [Hamlib-developer] Documentation plan

[Frank S. <vk...@ix...>]

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. 

Yes, lets tell people what its about, its goals, status, ambition,
world domination  ... :)

Our empty web space is not that eye-catching !!

A little diagram showing frontend API and the backends
would also help visualisation of the project.

Also some site navigation, status, FAQ, "latest news" areas 
etc would be good.

> After that is in place I'd like to expand that by
> documenting the version 1.1.0 API.  As this becomes complete it should
> probably be included in the next stable release.  Far into the future
> come things like HOWTO guides and radio command indexes and such.
> 

The frontend API has some markups to assist documentation.
Stephane, comments. Also the rig capabilities matrix would
be nice... :)

> Is there a preferred style for the web pages?  I don't plan on using
> frames or a lot of fancy gizmos.

Good, there are still a lot of us with low bandwidth 
connections (sigh..). Mostly I am not a frames fan,
although they occasionally provide some navigational 
use. I could live without them :^)

> 
> Finally, I installed the ssh (OpenSSH) 1.2.3-9.1 debian package
> yesterday, but cannot log into hamlib.sourceforge.net as the Sourceforge
> documentation indicates.  Is this reserved for the project owner, or is
> there some other reason (Frank?).  Or will I need to contact Sourceforge
> to get this resolved?
> 

Hmm, let me check, I just uploaded my pub ssh key and waited 24
hours, from memory...

I know there have been some problems with the sourceforge 
re-shuffle. eg: Our CVS commits are normally emailed our cvs-devel
list, but that stopped recently. I have a ticket open on it.


Welcome onboard Nate.

Cheers / Frank 

73's de vk3fcs & km5ws

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

Re: [Hamlib-developer] Documentation plan

[Nate B. <n0...@ne...>]

Hi Stephane!

On Wed, Jan 03, 2001 at 11:22:58PM +0100, Stephane Fillod wrote:
> 
>   The problem with API documentation is doco isn't updated when
>   code changes. That's why hamlib have hamlib-doc, a clone from kernel-doc,
>   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 pages.
>   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 
>   to someone else, and even to the coder who forgot his ugly tricks :).

Thanks for the tip.  I had glanced at hamlib-doc and now I'll give it a
go.  Right now I'm going to concentrate on the Web pages and I'll dig
deeper into the code afterward.

>   sounds a good plan to me. http://hamlib.sourceforge.net is as much needed
>   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 :) 
>   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

I looked at that page a week ago and it looks quite promising.  I did
glance at rigmatrix.c and will also investigate it further.

>   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)

I found it at linux1394.sourceforge.net and it is a nice looking page.

>   Very import too, I think we need a logo. You know, like a small
>   picture to identify Hamlib. I have no good ideas yet. 
>   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 
>   the Olympics games?). Do you have any other idea ?
>   Artists and gimp experts, this is time to show off!

Okay as I stated earlier, I'm no artist :-O  Volunteers??

>   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.

I was trying to use ssh to log into the server to get access to
uploading web pages.  Frank said something about needing to upload a
public key to sourceforge, but I saw nothing mentioned in their
quickstart docs.

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

If it helps ham radio and Linux, I'm pleased to be able to take part.

Also, I have uploaded a preliminary page for hamlib on my personal
webspace with my ISP.  You can look at it at:

http://www.networksplus.net/n0n/index.html

73, de Nate >>

-- 
 Wireless | Amateur Radio Station N0NB          | "None can love freedom
 Internet | n0...@ne...               | heartily, but good
 Location | Wichita, Kansas USA EM17hs          | men; the rest love not
   Wichita area exams; ham radio; Linux info @  | freedom, but license."
             http://www.qsl.net/n0nb/           | -- John Milton

Re: [Hamlib-developer] Documentation plan

[Frank S. <vk...@ix...>]

Nate Bargmann wrote:

> I was trying to use ssh to log into the server to get access to
> uploading web pages.  Frank said something about needing to upload a
> public key to sourceforge, but I saw nothing mentioned in their
> quickstart docs.
> 

Take a look at 

http://sourceforge.net/docman/display_doc.php?docid=765&group_id=1

and 

http://sourceforge.net/docman/display_doc.php?docid=763&group_id=1


-- 
Cheers / Frank 

73's de vk3fcs & km5ws