[Dirvish] Pod vs Man

Eric Mountain em-dirvish-1 at nerim.net
Wed Dec 22 14:48:39 PST 2004


On Wednesday 22 Dec 2004 16:18, Keith Lofstrom spake thus:
> our docs are in man format now.  In spite of my preference for pod,
> somebody must volunteer to convert the existing man documents to pod,
> and volunteer to test the pod-to-XXX conversion process.  We should
> weight the pro-pod votes, including my own, by the presence or lack
> of volunteers for the two conversion tasks.

Attached is a sample for dirvish-locate.  I can probably do the rest within a 
week or 2 if this is OK.

The derivative files were generated using:

pod2man --section=8 --release=1.3.0-esm 
--center="Dirvish" ../dirvish-locate.pod | man -l - > dirvish-locate.8

pod2html --infile=../dirvish-locate.pod --outfile=dirvish-locate.html 
--podpath=.. --noindex --title=Dirvish

pod2text ../dirvish-locate.pod > dirvish-locate.text  

The html conversion produces some warnings due to unresolved links.  I guess 
this can be fixed by converting the other man pages to pod.  Anyway, I'd say 
it's acceptable to get man page generation right first, and then work on the 
other formats if there are any issues (e.g. pod2usage generates slightly 
cruddy output, but it's trivial to fix), since that is the only format 
currently produced anyway.

Cheers,
-- 
Eric Mountain
-------------- next part --------------

=head1 NAME

dirvish-locate - locate file versions in dirvish images

=head1 SYNOPSIS

B<dirvish-locate> I<vault>[I<:branch>] I<pattern>

=head1 DESCRIPTION

Locate versions of files in a dirvish vault

The index of each image specified I<vault> is searched for paths
matching pattern.  Each path found matching the pattern will be
reported followed by a modification time of each version of the file
and all images having a link to it.

The optional I<branch> specification will restrict searching to the
specified branch.

Images with an error status will be skipped as will any without index
files.  The index file may be compressed by gzip or bzip2.  See B<tree>
and B<index> in L<dirvish.conf> for details.

The I<pattern> is a B<perl> regular expression to match the final component
of the path.  Append B<.*> to the end of the pattern if you wish to match
any substring of the whole path or B<$> if you wish to anchor the pattern
to the end of the path.  See L<perlre> for details.

Directories are excluded from matching as they would wind up matching
every file within them anyway.  Symlinks are also excluded from matching.

If the I<pattern> matches too many paths B<dirvish-locate> will only report
the paths matched and not versions.  As a sanity check if the number
of matches is really excessive B<dirvish-locate> will limit the number of
images searched.  Excessive matches is an indication of an
insufficiently specific I<pattern>.  Use the resulting path list to
compose a more specific one.

=head1 EXIT CODES

To facilitate further automation and integration of B<dirvish-locate>
with other tools B<dirvish-locate provides rationalised exit codes>.  The
exit codes are range based.  While the code for a specific error may
change from one version to another it will remain within the specified
range.  So don't test for specific exit codes but instead test for a
range of values.  To the degree possible higher value ranges indicate
more severe errors.

=over 4

=item *

0          success

=item *

200-219    An error was encountered in loading a configuration file.

=item *

220-254    An error was detected in the configuration.

=item *

255        Incorrect usage.

=back

=head1 FILES

=over


=item       /etc/dirvish/master.conf

alternate master configuration file.

=item       /etc/dirvish.conf

master configuration file.

=item       bank/vault/image/summary

image creation summary.

=item       bank/vault/image/index

=item       bank/vault/image/index.gz

=item       bank/vault/image/index.bz2

dirvish index file.

=back

=head1 SEE ALSO

L<dirvish.conf>

=head1 BUGS

None known.

-------------- next part --------------
DIRVISH-LOCATE(8)                   Dirvish                  DIRVISH-LOCATE(8)



NNAAMMEE
       dirvish-locate - locate file versions in dirvish images

SSYYNNOOPPSSIISS
       ddiirrvviisshh--llooccaattee _v_a_u_l_t[_:_b_r_a_n_c_h] _p_a_t_t_e_r_n

DDEESSCCRRIIPPTTIIOONN
       Locate versions of files in a dirvish vault

       The index of each image specified _v_a_u_l_t is searched for paths matching
       pattern.  Each path found matching the pattern will be reported fol-
       lowed by a modification time of each version of the file and all images
       having a link to it.

       The optional _b_r_a_n_c_h specification will restrict searching to the speci-
       fied branch.

       Images with an error status will be skipped as will any without index
       files.  The index file may be compressed by gzip or bzip2.  See ttrreeee
       and iinnddeexx in dirvish.conf for details.

       The _p_a_t_t_e_r_n is a ppeerrll regular expression to match the final component
       of the path.  Append ..** to the end of the pattern if you wish to match
       any substring of the whole path or $$ if you wish to anchor the pattern
       to the end of the path.  See perlre for details.

       Directories are excluded from matching as they would wind up matching
       every file within them anyway.  Symlinks are also excluded from match-
       ing.

       If the _p_a_t_t_e_r_n matches too many paths ddiirrvviisshh--llooccaattee will only report
       the paths matched and not versions.  As a sanity check if the number of
       matches is really excessive ddiirrvviisshh--llooccaattee will limit the number of
       images searched.  Excessive matches is an indication of an insuffi-
       ciently specific _p_a_t_t_e_r_n.  Use the resulting path list to compose a
       more specific one.

EEXXIITT CCOODDEESS
       To facilitate further automation and integration of ddiirrvviisshh--llooccaattee with
       other tools ddiirrvviisshh--llooccaattee pprroovviiddeess rraattiioonnaalliisseedd eexxiitt ccooddeess.  The exit
       codes are range based.  While the code for a specific error may change
       from one version to another it will remain within the specified range.
       So don't test for specific exit codes but instead test for a range of
       values.  To the degree possible higher value ranges indicate more
       severe errors.

       ·   0          success

       ·   200-219    An error was encountered in loading a configuration
           file.

       ·   220-254    An error was detected in the configuration.

       ·   255        Incorrect usage.

FFIILLEESS
       /etc/dirvish/master.conf
           alternate master configuration file.

       /etc/dirvish.conf
           master configuration file.

       bank/vault/image/summary
           image creation summary.

       bank/vault/image/index
       bank/vault/image/index.gz
       bank/vault/image/index.bz2
           dirvish index file.

SSEEEE AALLSSOO
       dirvish.conf

BBUUGGSS
       None known.



1.3.0-esm                         2004-12-22                 DIRVISH-LOCATE(8)
-------------- next part --------------
NAME
    dirvish-locate - locate file versions in dirvish images

SYNOPSIS
    dirvish-locate *vault*[*:branch*] *pattern*

DESCRIPTION
    Locate versions of files in a dirvish vault

    The index of each image specified *vault* is searched for paths matching
    pattern. Each path found matching the pattern will be reported followed
    by a modification time of each version of the file and all images having
    a link to it.

    The optional *branch* specification will restrict searching to the
    specified branch.

    Images with an error status will be skipped as will any without index
    files. The index file may be compressed by gzip or bzip2. See tree and
    index in dirvish.conf for details.

    The *pattern* is a perl regular expression to match the final component
    of the path. Append .* to the end of the pattern if you wish to match
    any substring of the whole path or $ if you wish to anchor the pattern
    to the end of the path. See perlre for details.

    Directories are excluded from matching as they would wind up matching
    every file within them anyway. Symlinks are also excluded from matching.

    If the *pattern* matches too many paths dirvish-locate will only report
    the paths matched and not versions. As a sanity check if the number of
    matches is really excessive dirvish-locate will limit the number of
    images searched. Excessive matches is an indication of an insufficiently
    specific *pattern*. Use the resulting path list to compose a more
    specific one.

EXIT CODES
    To facilitate further automation and integration of dirvish-locate with
    other tools dirvish-locate provides rationalised exit codes. The exit
    codes are range based. While the code for a specific error may change
    from one version to another it will remain within the specified range.
    So don't test for specific exit codes but instead test for a range of
    values. To the degree possible higher value ranges indicate more severe
    errors.

    *   0 success

    *   200-219 An error was encountered in loading a configuration file.

    *   220-254 An error was detected in the configuration.

    *   255 Incorrect usage.

FILES
    /etc/dirvish/master.conf
        alternate master configuration file.

    /etc/dirvish.conf
        master configuration file.

    bank/vault/image/summary
        image creation summary.

    bank/vault/image/index
    bank/vault/image/index.gz
    bank/vault/image/index.bz2
        dirvish index file.

SEE ALSO
    dirvish.conf

BUGS
    None known.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.dirvish.org/pipermail/dirvish/attachments/20041222/473631d2/dirvish-locate.html


More information about the Dirvish mailing list