#20 CPAN-friendly .pd files

None
closed
nobody
None
3
2015-02-05
2010-02-08
David Mertens
No

I have already turned slices.pd into a CPAN-friendly .pd file. The next step is to update PDL's documentation on writing documentation with guidelines on making CPAN-friendly .pd files. At the same time (or afterwards, or beforehand) I need to slog through the rest of the .pd files in the source tree and transition them.

Discussion

  • Chris Marshall
    Chris Marshall
    2010-04-20

    I recommend using podchecker to determine when a file is "CPAN-friendly".
    For example, running:

    podchecker Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 116 in file Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 171 in file Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 1097 in file Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 1141 in file Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 1335 in file Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 1683 in file Basic/Slices/slices.pd
    *** ERROR: Spurious text after =cut at line 2289 in file Basic/Slices/slices.pd
    Basic/Slices/slices.pd has 7 pod syntax errors.

    A look at the slices.pd file shows that these are all cases where the =cut
    directive is not on a blank line separated line by itself. These same errors
    also correspond to the remaining glitchs in the search.cpan.org auto-POD
    extraction "feature"....

     
  • Chris Marshall
    Chris Marshall
    2010-04-20

    • priority: 5 --> 3
     
  • Chris Marshall
    Chris Marshall
    2011-02-14

    podchecker has been run against all the PDL *.pd files.
    There were basically two types of ERRORs found:

    (1) =cut (or other POD command) without a following empty line

    (2) unresolved local links

    Current PDL git has all the problems from case #1
    fixed. However, the case #2 arises because the
    text to link to is generated by the pp_def() at compile
    time and so does not exist.

    FWIW: Here is the process to fix a file:

    (1) run podchecker on it. E.g.:

    *** ERROR: Spurious text after =cut at line ...
    *** ERROR: Spurious character(s) after =back at line ...
    *** ERROR: Spurious text after =pod at line ...

    (2) for each ERROR with =cut or other POD construct,
    add a blank line following the =cut

    (3) rerun podchecker on the file to verify your fixes

     
  • Chris Marshall
    Chris Marshall
    2011-03-25

    The checks against the remaining .pd files has been made
    and the CPAN docs generated from them are much improved.
    TODO: add documentation on style for authors of future .pd
    files. An alternative approach would be for the generation
    of the documentation be part of the release process rather than
    occurring only at build time.

    Should be fixed for the PDL-2.4.8 release.

     
  • Chris Marshall
    Chris Marshall
    2015-02-05

    Recent docs fixes for the distribution have addressed this problem as well.

     
  • Chris Marshall
    Chris Marshall
    2015-02-05

    • status: open --> closed
    • Group: -->