INN manual

[eagle]

A full-blown manual for INN would be great. Here is some discussion from an e-mail message that I sent in 1999.

We currently already have what's essentially a reference manual; that's the collection of all of the man pages plus the three README.*_hook files. They need some glue, and more extensive cross-referencing, but that's not too hard.

We have the beginnings of an introductory guide, in the form of README (after the work I did about a month ago) and INSTALL, plus pieces of Elena's document. What that mainly needs at the moment is an overview of how INN works, including descriptions of the major files involved, stuck in-between those two documents and some documentation of the periodic maintenance tasks that one has to do stuck after INSTALL.

We need more general discussion of how specific parts of news work and how to do specific things; we currently have a doc on control messages but that's about it. I have a few things planned here. Part of what should go in this part is schemes for setting up specific types of servers. (If I want a basic feed and reader machine, what do I do? If I want a split feed and reader setup, what do I do? If I want to share the same reader spool across a bunch of machines, what do I do? If I want to set up a standalone server for a particular hierarchy, what do I do? How do I run nnrpd standalone rather than from innd?) Elena's document has some of that.

We're badly missing internals documentation, apart from a few really outdated library man pages.

The overall structure I'd like to see is something like this:

• Introduction

• Basic Usenet Concepts

• User's Manual
  • Building and Installing INN
  • Configuring INN
  • Maintaining INN
  • Platform-Specific Issues

• Configuration Manual
  • Specific Setups
    • Mixed Feed and Reader
    • Separate Feed and Reader
      • INN as Feed Machine
      • Other Server as Feed Machine
    • Farm of Readers With Same Spool
    • Standalone Public Server
  • Performance Issues
    • Major Bottlenecks
    • Choosing a Disk Layout
    • Tuning an INN Server
  • Filter Configuration
  • Namespace Management
    • Control Message Processing
    • Using actsync

• Reference Manual
  • Primary INN Programs
  • Configuration Files
  • Maintenance and Recovery Programs
  • File Formats
  • Library Interfaces
  • Special Issues
    • RFC Compliance
    • Theory and Practice of Control Messages

• Programmer's Manual
  • Code Structure
  • Major Data Structures
  • Documentation Maintenance

Anyway, that's entirely off the top of my head just now, but if you look that over, we actually have a surprising amount of that already. Particularly if you count the stuff that was in the old FAQ. It just isn't well-organized, tied together, explained, cross-referenced, and indexed.

Getting documentation, any documentation, is more important right now than any particular structure, but I'd strongly encourage people to think in terms of a structure like the above and have at least a tentative idea of where the documentation that they're writing would fit in. That way, it will be much easier for us down the road to produce a coherent and readable overall set of documentation.

[Julien ÉLIE]

[Julien Élie]
By the way, as for a possible texinfo documentation in the future, why wouldn't it be generated by pod2latex from existing documentation?
I believe the organization you have done in your website is quite good (introduction, developers, filtering, conf files, daemons, data files, etc.) and it could be used for the texinfo documentation.
The only missing stuff would be a little glue between the different sections and it could be achieved with an additional intro-*.pod for each section.

As a matter of fact, I do not think maintaining another documentation for texinfo only is a good idea. It is already hard enough to keep a documentation up to date! So the easiest thing I see is generating a texinfo documentation directly from existing POD files: for each section, a special overall introduction followed by the juxtaposition of existing manual pages.

Or perhaps do you have another idea?

[Russ Allbery]
The main reason for going to texinfo, which I thought of as a very long-term project, is that it's really a nicer language for writing a real, printable manual in than POD is. Unfortunately, the HTML output isn't always great, but it provides much better typographic control and the printed output is wonderful. It also provides chapters, indexes, a table of contents, and other things that are mostly a hack in POD.

If we went to texinfo, it would probably be as a comprehensive rewrite of the current INSTALL and checklist as a full-blown manual, keeping the man pages for detailed reference (since everything should have a man page in addition). I could see putting a lot of information about INN's internals into a texinfo document as well.