Re: Linux documentation

On Sat, Sep 15, 2007 at 12:14:56AM -0700, Steven wrote:
> Re html man page documentation (i think), jdddodin.org
wrote:

> Would LDP posters be interested in a petition/campaign
to GNU to
> ditch info pages and consolidate man pages as their
definitive
> reference ? This will give everyone else a cornerstone
to make up
> their own hyper linked and more attractive
documentation, without
> the need for fancy ad-hoc wikis that say "Oh yeah,
there's a new dvd
> udf filesystem standard that only works with kernel
2.6.NN.  The
> mount manpage doesn't know anything about it". I
realize hassling
> GNU mightn't achieve much, and personally I'm not much
of a diplomat
> myself ;> but who knows. One day RMS may start
listening to other
> people, or, more likely, some one else will gain
effective control
> of GNU's utilities. And maybe if we make a noise there
will be
> plenty of other voices.

The problem is that info has hyperlinks while man pages
don't (at
least not one's you click on unless it's in html format). 
Another
problem with man-pages is the groff format source.  I would
suggest that
linux-doc could be improved so that manpages could be
written in
linux-doc and then converted to html, groff, etc.  Linuxdoc
already
converts to groff as an intermediate step in converting to
plain text.
It also converts to info pages using sgml2info.  Does
docbook also
convert to info?  What would be needed would be a converter
from info
to linux-doc.

But the problem of integration of Linux documentation is
much more
than this and was discussed with hundreds of postings to
ode-discussoswg.org.  (ode = open documentation environment;
oswg =
open source writers group).  But it seems that the archives
of this
discussion have been destroyed and the domain name is up for
sale.
However, they never reached any consensus of what's needed. 
I think
someone was going to summarize the various proposal but
never did.
But not much has been lost.  I'm worried that ldp.org may be
up for
sale too if someone doesn't obtain it from Poet who
presumably still
owns it.

			David Lawyer

______________________
http://lists.tldp.org/

> I would suggest that
> linux-doc could be improved so that manpages could be
written in
> linux-doc and then converted to html, groff, etc. 

Laugh. It'd be nice.

> I'm worried that ldp.org may be up for
> sale too if someone doesn't obtain it from Poet who
presumably still
> owns it.

Do you mean tldp.org ? I haven't followed the domain name
saga too much, but ldp.org
seems a little ... unaffiliated, already.

Is discussen.tldp.org archived anywhere ?

S.A.



       
____________________________________________________________
________________________
Boardwalk for $500? In 2007? Ha! Play Monopoly Here and Now
(it's updated for today's economy) at Yahoo! Games.
http://get.games.yahoo.com/proddesc?gamekey=monopolyh
erenow  

______________________
http://lists.tldp.org/

David Lawyer writes:

> least not one's you click on unless it's in html
format).  Another
> problem with man-pages is the groff format source.  I
would suggest that
> linux-doc could be improved so that manpages could be
written in
> linux-doc and then converted to html, groff, etc. 
Linuxdoc already
> converts to groff as an intermediate step in converting
to plain text.
> It also converts to info pages using sgml2info.  Does
docbook also
> convert to info?

Converting manpages to Docbook will not automatically give
you hyperlinks. 
Links in Docbook XML are limited to internal links to other
parts of the 
document. If you assemble a set of manpages into a single
Docbook XML 
document, you can have manpages inside the set linking to
each other. But if 
each manpage is a standalone document, it won't be able to
link to anything 
else. Not unless you apply a custom stylesheet after
converting the document 
to HTML. This is not hard, but now you're getting away from
an ordinary 
Docbook XML document, and introduce your own hacks on top of
it.