Questions about Perl and doc

[Julien ÉLIE]

En réponse à Russ Allbery :
>> That is to say innshellvars.pm which defines 'package inn' and only
>> exports variables with EXPORT_OK (so as not to pollute the namespace)?
>
>> And then fixscript would put:
>>     use lib '@libdir@';
>>     use innshellvars;
>
> It should really be called something like INN::Config, but yes, that's the
> basic idea.

Wouldn't it imply the creation of a subdirectory for the file
@libdir@/INN/Config.pm?  or even better @libdir@/perl/INN/Config.pm?
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.

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'd be tempted to do something like inn(7) for the install guide, since
> it's also a general introduction to INN, although the section numbers
> other than 1, 2, 3, 5, and 8 vary a lot between systems and on some
> systems that's going to look like a very odd section for it.

It is difficult to avoid such "weird" sections for some systems.  It is
a general install guide after all.  I believe users will manage to find out
what is for their system and what is not (and they will just skip the
irrelevant section).


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


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.
(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!
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?

-- 
Julien ÉLIE

« -- Vous n'avez rien à déclarer ?
  -- J'ai faim.
  -- Qu'est-ce que vous avez là ?
  -- Un creux ! » (Astérix)