Documentating the configuration files

[Jan Fabry]

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 at 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