Re: Request for doc writers / ideas on what to write.

[Erik Walthinsen <omega@omegacs.net>]

> 4. Format of the help files. Currently the help system
>    only supports html. A plugin which will be included
>    in the future may be for the sdoc format (seul doc...)
>    This is being looked in to currently.

If sdoc becomes what I have in mind right now, sdoc would be the primary 
format.  Or rather, sdoc parsed into appropriate html constructs, then 
displayed (we'll need some efficiency work done once it works...).  The idea 
in question is that of conditional parsing of sdoc.  The use that triggered 
the idea was the .info files for the mailing lists and keeping pages on the 
web up-to-date with them.

In the case of the help system (another idea I just came up with), you would 
have an sdoc file with the right doc type (which puts certain pieces of perl 
code behind various tags), and a conditional for the user level.  Then you 
have parts of the file set up in different levels of detail, with pieces 
specific to the 'guru' level or the 'novice' level, and others that are 
generic to all.  When the file is parsed with the appropriate level defined, 
the right document comes out.

This allows the maintainer to have a single file with all the data, 
formatting, etc., sharing what can be shared and dealing with each user 
level differently, as appropriate.

This conditional ability doesn't have to be limited to the expertise level, 
either.  In the case of system management (if we use the help browser for 
that), conditionals or some other mechanism (which is definable by the extra, 
non-parser perl code) could be used to determine what packages are installed, 
and tweak things appropriately.  For instance, a novice-level security 
control panel for a machine that's on a corporate LAN (which is drastically 
different from the exact same control panel when used on a dialup machine) 
might have an extra check-box for the dhcpcd server, if they happen to have 
it installed, with 'dhcpcd' a link to the documentation for that server.  If 
they don't have it installed, it doesn't show up.  But it's always the same 
control panel, and nothing special needs to be done to create it.


I'll have to take what we have for the sdoc spec, what I want it to do, and 
merge the two into something that could be abstracted to do something like 
the above.  I don't know about everyone else, but the above sounds like it 
could make controlling a system many times easier, not only for the user, but 
for the people actually writing the system.

Comments *requested*....

TTYAL,
     Omega

      Erik Walthinsen - SEUL Project infrastructure/system architecture
        __
       /  \           omega@sequent.com         Work: (503)578-5314
      |    | M E G A  omega@omegacs.net         Home: (503)281-4281
      _\  /_          psu12113@odin.cc.pdx.edu  Majoring in CS

       SEUL: Simple End-User Linux - creating a Linux distribution
     http://www.seul.org/            for the average home/office user



===
SEUL-Leaders list, seul-leaders-request@seul.org
===