Allways during my late night hacking sessions I try to find something
useful todo while waiting for compile jobs, this is tonights task.
Doing a overhaul of the Hurd Reference manual.
The major grief I have with it is that it is organised in a stupid
way. The following "list" is how I want to reorganise everything
(don't want todo a major overhaul just to see that "no, that is not
the way todo it" :):
* Have all the invokation sesctions scattered around, it is a
reference manual so this should all be in one section call
"Programs" or similar.
* Skip the whole concept of "Foundations" and "Input and Output"
chapters, put all libraries under one chapter called "Libraries",
and give each chapter a suitable name.
* Put all translators under a chapter called "Translators", with a
short introduction to what a translator is, and then a list of all
avaiable translators. A section to this chapter might be similar to
what is now, "Distributed file-systems" etc. But this is probobly
not needed.
Why this kind of a structure? Because it is a reference manual, you
don't try to ponder about if the library is some kind of a
"foundation", or if a translator is "distributed". You look for the
major keyword, "library" or "translator". If you are trying to figure
out what a program, say "settrans", does, you don't look for "Files";
you look for "program".
For chapters that have lots and lots of sections, like "Program
Invocation", then one could split it into seperate sections, and put
each program into a sub-section.
I am not sure how I would send patches for this, should it be one big
that just does everyone in one go? Several small ones?
Note that my purposed layout has removed the whole "Bootstrap"
chapter, most of it isn't relevant anymore, serverboot is dead, and
the only interesting and useful thing in it that suits a reference
manual is how to fire up a sub-hurd.
Here is a modifed version of texinfo-show-structure of how I would
like to (more or less, some bits might be missing, but it should give
the general idea of how things would look like, so ignore any glaring
errors or stuff like that) modify the reference manual:
@top The GNU Hurd
@chapter Introduction
@section Audience
@section Features
@section Overview
@section History
@section GNU General Public License
@chapter Program invocation
@section Invoking boot
@subsection Boot Scripts
@subsection Recursive Bootstrap
@section shutdown, halt
@section pfinet
@section pflocal
@section ps, w
@section addauth, rmauth, setauth
@section su, sush, unsu
@section login, loginpr
@section Invoking @code{settrans}
@section Invoking @code{showtrans}
@section Invoking @code{mount}
@section Invoking @code{fsysopts}
@section storeinfo, storecat, storeread
@section ftpcp, ftpdir
@section nfsd
@chapter Libraries
@section Threads Library
@section Ports Library
@subsection ...
@section Integer Hash Library
@section Misc Library
@section Bug Address Library
@section Iohelp Library
@subsection ...
@section Pager Library
@subsection ...
@section I/O Interface
@subsection ...
@section Fshelp Library
@subsection ...
@section File Interface
@subsection ....
@section Filesystem Interface
@section Store Library
@subsection ...
@section Trivfs Library
@subsection ...
@section Diskfs Library
@subsection ...
@section FTP Connection Library
@section libpipe
@section Socket Interface
@chapter Translators
@section Linux Extended 2 FS
@section BSD Unix FS
@section ISO-9660 CD-ROM FS
@section symlink, firmlink
@section hostmux, usermux
@section shadowfs
@section ftpfs
@section nfs
@section fifo
@section ifsock
@section magic
@section null
@section term
@section exec
@section proc
@section crash
@section auth
@subsection Auth Protocol
@unnumbered Index
_______________________________________________
Bug-hurd mailing list
[EMAIL PROTECTED]
http://lists.gnu.org/mailman/listinfo/bug-hurd
