Questions about Perl and doc

[Russ Allbery]

Julien ÉLIE <julien at trigofacile.com> writes:

> Wouldn't it imply the creation of a subdirectory for the file
> @libdir@/INN/Config.pm?  or even better @libdir@/perl/INN/Config.pm?

Yes.

> I thought 'use innshellvars' (or whatever name) would load
> @libdir@/innshellvars.pm which would define 'package INN::Config'.
> Then, everything would work fine with calls to $INN::Config::pathetc for
> instance.

We could do it that way, but creating a real INN::* hierarchy of Perl
modules would be useful if, say, we had a real Perl API to the
configuration parsing interface, or a Perl API to the storage system
(which could make some programs like cnfsstat much nicer), or a Perl API
to the ctlinnd interface so that ctlinnd operations could be done
natively.  All of those modules have been written and/or contributed at
various points in the past and I mostly hadn't integrated them because we
didn't have a structure.

> But well, it would allow to have @libdir@/perl/INN/innreport.pm too :)
> (or @libdir@/perl/INN/Report.pm?)
> What do you think about that?

I think that's a good idea, although innreport is an odd beast with a
fairly unusual Perl style and probably could stand more surgery than
that.  But a little bit at a time.  :)

>> The checklist seems to be of more marginal utility after installation
>> to me.

> Sure, but for quick reference (or hurried people), it can be of help too.

I certainly have no objection to installing it as inn-checklist.

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

Realistically, I'm probably not going to have time to do this.

> 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.  (I hope I am clear enough in my explanations here and
> that you understand what I mean.)

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

Agreed, it would only be worth doing if we actually replaced substantial
chunks of documentation with it, and there are a lot of more pressing
issues we should work on first.

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

I don't think you can really convert POD to texinfo effectively, since the
latter is a much richer format.  The texinfo manual probably isn't a great
idea right now.  inn-intro pages for various man page sections that point
to all of the available utilities and documentation sound like a great
idea, though.

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>

    Please send questions to the list rather than mailing me directly.
     <http://www.eyrie.org/~eagle/faqs/questions.html> explains why.