Karsten Wade wrote:
On Fri, 2003-12-26 at 15:18, Jan Fabry wrote:
>Hello,
>
>Are there any plans to documentate the configuration files, and their
>relationship to each other? I know Fedora is a end-user-oriented
>project, but for that one case when you need to change something for
>which there is no GUI, it's not always easy to know where to start ("if
>I want to add a directory to my path, where should I put it?").
>
>The man pages alone don't always offer all the information you need:
>configuration files can be very distro-specific, and might put the usual
>configuration files in a totally different context.
>
>If this doesn't fall under the scope of this project, I might start
>something like this on my own, but of course it's always easier if we
>work together.
This is an interesting idea. It is reminiscent of the RHEL Reference
Guide
(
http://www.redhat.com/docs/manuals/enterprise/RHEL-3-Manual/ref-guide/), which has many
chapters devoted to config files. Of course, something of that size and type _is_ out of
scope for the Fedora docs project.
Wow, I never knew this document existed. Indeed, it is a very good start
for what I want.
However, a very tight config file reference that was e.g. organized
sets
of files done as multiple <variablelist> entries would be very useful,
even if such a reference work is outside of the FDP scope.
The real question is, how do you decide what exactly to document?
[root@erato etc]# find . -type f | wc -l
1543
That's a whole bunch. I would be concerned that no matter what number
and which files you chose to document, you would have a stand alone
document requiring regular manual maintenance, and which is somewhat
duplicating the effort of the man pages (deficient as they might be).
I like Dave's idea: a list of all the files, so you can at least refer
to them in other documents. This way, if the location of a file changes,
or it is split over multiple files, all the referring docs don't get
outdated too soon. And indeed, we could start there, and link to other
documentation resources from there.
Another viewpoint would be to take the effort for doing this stand alone
reference and put that into updating the man pages. An updated man page
should contain a complete list of all relevant config files, which then
may have their own man pages, and which should be self-documented inside
the config file itself (in comment blocks). For *nix, this is the
proper place for documentation - comes loaded on the system and doesn't
require a separate reader and a network connection to access. I'd
rather teach users to rely upon those resources, if it were all up to
me.
But it would be nice if we could integrate man, info, howto, whatever
into one system, which chooses the best output format in any given
situation (when you're using the terminal in Gnome, it would be no
problem to start a GUI help system for example).
We've been contemplating for a while what such a project would be like.
Huge. That's about the size of it. However, if the FDP group were to
take on this task, we might be able to get the Linux Doc Project to let
us convert all of the man pages to DocBook XML. ;-)
This would be great - instead of taking the man, info, whatever files as
a source of the Fedora documentation viewer, we would only use Docbook
files, and convert _them_ to man, info, whatever. This would take Linux
documentation to a whole new level, with standard ways of referring to
each other and stuff like that. We have the tools to do this, we only
need people willing to do it.
The Fedora help viewer would then only need to know about this
Docbook-based format. When new documentation is added, it is also
indexed for easy searching. I don't know if GTK has a standard help
system, but it would be great if we could integrate this (a bit like
Apple's help viewer - if I open help for Safari, I can also search for
help on iTunes and other applications using this help system).
My ultimate dream would be a universal 'whatis'. You can type 'whatis
[filename]', and it would tell you as much as it knows about that file.
If no real documentation would be found, you get the file(1) information
about it, or some other backup information. But that is of course a long
way ahead...
But to start: I'm very interested in this man pages -> DocBook
conversion. I have already found docfilter [
http://www.catb.org/~esr/doclifter/ ], a tool to help with this
conversion. Any other pointers to more info?
Greetings,
Jan Fabry