[OpenAFS-Doc] Re: [OpenAFS-devel] The OpenAFS man page project

[ted creedon]

Could you clarify where non-transarc ( bin  db  etc  local  logs  ) are 
to be kept for client and server?

Could the documentation be kept uncoupled from the normal build tree? At 
some point in time there might be a major revsion in the documentation 
and getting it tangled up in the build tree guarantees that the docs 
will ALWAYS be out of sync with  the release.

At least that's the way it is now.

tedc

Jeffrey Hutzelman wrote:
> Without having looked at the source Russ committed...
>
> On Friday, December 09, 2005 03:28:43 PM -0800 Russ Allbery 
> <rra@stanford.edu> wrote:
>
>
>
>> The POD source is converted to formatted man pages as part of running
>> regen.sh so that consumers of release tarballs won't have to have 
>> pod2man
>> available to get man pages.
>
> OK, but since man pages are not an essential operational part of the 
> system, people checking things out of CVS should _also_ not be 
> required to have pod2man available in order to build the software.  I 
> would suggest that regen.sh check for availability of pod2man, and if 
> it is not available, print a warning and move on.
>
> In an ideal world, this would be fatal when building release source; 
> one way to do this would be to make regen.sh take a command-line 
> switch which, when given, indicates that this is a release build and 
> it should be more strict.  We can then cause make_release to use that 
> switch when constructing the source tarballs for releases.
>
>
> While I generally support the idea of building the man pages at regen 
> time, I anticipate that folks packaging OpenAFS may want to run 
> pod2man on the "right" platform, to get more consistency with whatever 
> conventions are used on that platform.  It might be good to do 
> something to facilitate regenerating the man pages without doing the 
> autoconf step.  Similarly, as the number of man pages gets large, we 
> may actually want regen to run a make-like operation so only pages 
> which do not exist or whose sources have changed get rebuilt.
>
>
>
>>   The quality of the conversion should be
>> adequate for any version of Perl released in the past five years, but 
>> for
>> best results you want to use pod2man that comes with Perl 5.8 or 
>> later, or
>> alternately install Pod::Simple 3.03 (or later) and podlators 2.00 (or
>> later) from CPAN before running regen.sh.
>
> Again, I think it would be good for the script to print a warning if 
> the best tools are not available.
>
>
>> The breakdown of man pages between sections is somewhat arbitrary,
>> particularly since I wanted to keep command suites together.  Yes, 
>> vos is
>> in section one and bos is in section eight and this doesn't necessarily
>> make a tremendous amount of sense.  If someone comes up with a clear
>> guideline for what should go where, I'm all ears; in the meantime, this
>> seemed vaguely reasonable, and we can always move commands later.
>> Unfortunately, where OpenAFS itself installs commands (bin or etc or
>> root.server) also needs to be reviewed and isn't a particularly great
>> guide.
>
> Well, when you talk about etc and root.server, you're clearly looking 
> at where things are being installed in the transarc-paths case.  That 
> case exists for compatibility, and so deliberately installs things 
> where AFS has always installed them.  It should not be changed.
>
> For the non-transarc-paths case, we chose to install things according 
> to GNU conventions, in which
>
> - binaries that will be invoked by ordinary users are installed in bin
> - binaries that will be invoked by system administrators, either directly
>  or indirectly (e.g. by system startup scripts) are installed in sbin
> - binaries that are normally invoked only by other programs are installed
>  in libexec/openafs
>
> Things in the first category should be documented in man1.
> Things in the other two categories should be documented in man8.
>
>
>
> Thanks for all the work you've done on this, Russ.
>
> -- Jeff
> _______________________________________________
> OpenAFS-doc mailing list
> OpenAFS-doc@openafs.org
> https://lists.openafs.org/mailman/listinfo/openafs-doc
>