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
