[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-docbook
Subject:    Man pages
From:       Lauri Watts <lauri () kde ! org>
Date:       2001-05-06 13:09:05
[Download RAW message or body]

Before we start adding man pages, there's a few things I need to figure out.

Since at least one linux distribution insists on a man page for each binary, 
these documents *will* be written anyway, even if we don't do it ourselves, 
it makes sense that we make use of this fact, and include this information in 
the main KDE documentation.

docbook2man relies on jade + perl, and using the new help:/ kioslave has 
removed our reliance on jade in particular, so I hardly want to be 
responsible for adding that back.  That leaves generating man pages from xsl 
stylesheets (Frederik, you mentioned this was already possible? do you know 
how?) or if coolo wants to make the man converter he wrote work on refentry 
markup instead.

Where is an appropriate place for the sources to go?  

Depending on the tool used to process these,  it could be as: 
module/docs/manpages/<appname>man.docbook, or something like this.  I'd 
prefer to not have another subdirectory for each binary. For example, in 
kdebase there are more than 60 binaries, and 14 subdirectories in /doc/.  I 
don't think adding another 46+ subdirectories to /doc/ would be all that 
efficient , nor would it be too manageable.

Perhaps there can be a per module /doc/index.docbook, with each separate 
manpage being included from a /man/ subdirectory in the same way as the 
kcontrol modules are. This makes the most manageable solution to me, for 
multiple authors, so long as the processing tool doesn't rely on the files 
being named index.docbook. 

This thought appeals to me, because we could use the documentation ourselves 
in other ways.  Something I have in mind is that the docbook source could be 
installed, so that calling help:/kdebase would give you short introduction on 
what the kdebase module contains, with links to it's major application 
handbooks, and then the reference sections for the smaller binaries that 
don't have or need their own manuals. 

-- 
Lauri Watts
KDE Documentation Team

_______________________________________________
Kde-docbook mailing list
Kde-docbook@master.kde.org
http://master.kde.org/mailman/listinfo/kde-docbook

[prev in list] [next in list] [prev in thread] [next in thread]