Re: HOWTO-HOWTO recommendations

[Stein Gjoen <sgjoen@mail.nyx.net>]

Gary Preckshot wrote:
> 
> Stein Gjoen wrote:

Some misattribution here, not sure how that happened.

> > Consider this as an addition to the H-H style guide:
> >
> > "Write concisely. Organize, organize, organize. Ask yourself these three
> > questions:
> >
> > "1. Does every topic contribute to the goal of the document?
> >
> > "2. Does every subtopic contribute to the goal of the parent topic?
> >
> > "3. Does every sentence within a subtopic contribute to the goal of
> > the subtopic?"
> 
> I second that.
> 
> > > I am not sure myself. The process concists of a number of steps, not all
> > > are Linux specific. The Template itself could be used to document systems
> > > based on VAX/VMS if you wish. Here is how I see it:
> > >
> > >  1:get tools and start      H-H        Linux Specific
> > >  2:intro to SGML            H-H?       General purpose
> > >  3:intro to LinuxDoc        example/T  Linux specific
> > >  5:style guide              soon in T  LDP specific, possibly general
> > >  4:get template and write   Template   General purpose
> > >  5:submission to LDP        H-H        LDP specific
> > >  6:link checking            linkcheck  General purpose/HTML
> 
> I thought the LDP was going to DocBook 3.1. If there's an "intro to LinuxDoc," there
> ought to be an "intro to DocBook" and there ought also to be an explanation of why two
> DTDs are being referenced. Also, jade and Norman Walsh's DSSSL seem to work with
> DocBook, not LinuxDoc. Is this true? And shouldn't it be noted?

LinuxDoc has the advantage it works, works reasonably well, works today,
is small in size and resource requirements. The alternative seems less so
and many have reported problems in installation, usage and requirements.
There is also the tools confusion between SGML-Tools v2 and SGML-lite. I
am quite confused about what parts work with what in the DocBook scene and
when I see control characters leaking into the final rendering I feel it
is not as mature as LinuxDoc.

Both share a big problem of lack of properly documentation but I hope my
Template and Link Check documents will help here for LinuxDoc at least.


Regards,
   Stein Gjoen


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org