Re: [avrdude-dev] first cut texinfo manual

[Theodore A. Roth]

On Sat, 1 Mar 2003, Brian Dean wrote:

:)On Sat, Mar 01, 2003 at 09:26:46PM +0100, Joerg Wunsch wrote:
:)
:)> I think it's OK to review it afterwards.
:)> 
:)> I'd say "yes" to both other questions.  (Would have been nice to have
:)> a "src" subdir for all the stuff that's currently there, but that's
:)> quite a bit too late now i'm afraid.)
:)
:)Agreed.  Too bad we can't use rsync to overwrite the repo files on
:)savannah, that way we could more easily do repo surgery without having
:)to bother the savannah admins, whom I'm sure are overworked and
:)underpaid :-) If we really wanted to restructure, one of us could
:)rsync the repo to our local system, then tar it up and ask the admins
:)to overwrite the existing repo with the new one provided.  They'd
:)probably be willing to do that as long as we weren't asking for that
:)kind of thing too often.

Now would probably be a good time to do this. I'd much prefer to have the 
source down in a src subdir. Just makes things cleaner.

I'm sure if you give the savannah hackers a list of files, they can do the 
repo move for you with minimal interruption. It's should really only be a 15 
second operation.

:)
:)Anyway, the manual is committed.  I put myself as copyright, but I'm
:)not strongly tied to that.  I think we have to use someone - I don't
:)think a project name will work.  Also, I tried to give a brief
:)history, naming major contributors by name.  Most people who've
:)contributed are listed in the CHANGELOG for their contributions but I
:)thought it would be appropriate to list those who have been involved
:)in this transition effort directly in the manual.  If you all think
:)that is something better for the CHANGELOG, feel free to axe that.
:)I'm not sure how much of Radek's work that Eric used in the Window's
:)port - we should maybe list his name along side the rest.  I'm not
:)tied to naming names, its merely a suggestion and a starting point.
:)My opinion on giving credit is that the only payment people get for
:)contributing is the recognition, so we should give that freely.

That sounds fine. Personally, I've reached a point where I don't care if 
I'm mentioned in projects anymore, but that's up to you.

:)
:)My overall opinion of the manual is that nothing that is currently
:)there is set in stone - if others have ideas about better structuring
:)/ chapters, etc, feel free.
:)
:)Regarding a few specifics ... I ran into line overruns when including
:)some sample program output.  I don't know how to avoid that.  Also,
:)the texinfo formatting seems straitforward enough, but this is the
:)first I've used it, so expect misuses of some of the formatting
:)controls and places where I should've used something else.  While I
:)started with Ted's texinfo document for simulavr which privide nice
:)examples for how to use texinfo for a manual like this, I did not even
:)try to keep the @node type info navigation controls.  First, I'm not
:)sure how it all ties together, and also I figured it would be
:)pointless until the document settles down a little bit, otherwise
:)there would be twice as much stuff to change as the structure evolved.

As for the nodes and menus and such, emacs is your friend:

To update every node: C-c C-u C-e
To update all menus:  C-c C-u C-a

emacs-21 has a "Texinfo" menu with all kinds of goodies.

Have a look at the texinfo manual for more gory details.

  http://www.gnu.org/manual/texinfo/html_node/index.html

for emacs texinfo-mode:

  http://www.gnu.org/manual/texinfo/html_node/Texinfo-Mode.html#Texinfo%20Mode

:)
:)So anyway, there it is.  Its rough, but its a start.  Please feel free
:)to make wide sweeping changes :-)


Ted