NAME

Pod::Literate - Literate programming through POD, for general applications or specifications managed by AI/Copilot/Claude/ChatGPT

VERSION

Version 0.0.4

SYNOPSIS

podweave.pl  Module.pod | pod2text
podtangle.pl Module.pod
perl -e 'use Module; ...'

DESCRIPTION

Literate programming naturally structures code based on its written specification. Traditionally this permitted organization of very large applications in languages that initially focused on single-file development, which slowly extended to multiple files used as basic imports. With the advance of projects spanning many directories and isolation into objects, and the propensity to author code with minimal comments and documentation, literate programming became an historical curiosity.

With AI/LLM tools focused on software development assistance, it is possible to leverage literate programming to build specifications for applications and interfaces. Given the natural-language focus of this approach, LLMs benefit from and can better maintain consistency with specifications. Code again becomes focused on small, isolated, well-tested goals that can be merged together to form larger systems.

These specifications can be processed in two ways. A tangle command permits coalescing all named sections into the final application. A weave operation generates the specification with all relevant visible elements. In Pod::Literate, the weave application is perlpod itself and its associated formatters (pod2man etc.).

Backwards Incompatibility

IMPORTANT: This is an early version. Monitor the version change logs for additional information about forthcoming functional changes.

Spacing behaviors

Spacing behaviors of =begin and =for have been fixed/established in 0.0.4!

Section declaration versus addition

The warning/error behavior of literate Name versus literate +Name may change, be dependent on commandline flags, etc.

Unused sections

Unused sections may become failures, warnings, etc.

Weave

Weave options and overall behaviors are subject to change.

FORMAT FEATURES

The module, Pod::Literate, is implemented using the formatting features of perlpod. At this time, either =begin or =for may be used to declare named sections of code. They have different end-of-line behaviors. Both declarations are visible when using the weave command, but perlpod will hide the =begin sections if weave is not used first.

begin and end

The begin and end command paragraphs are used to create named sections of code, and must appear in pairs:

=begin literate Descriptive name

...

=end literate

When processing the start of these blocks, a title attribute is set with the "Descriptive name" which is used to identify the target section into which the text contents will be stored. The begin/end is best suited for code blocks, such as complete subroutines or functions, because the final blank line before the =end will be included in the code. These sections will be hidden with plain perlpod, but are visible when using weave.

Notice, at this time, that the classic additive syntax for a named section is supported, in particular

=begin literate +Descriptive name

...

=end literate

but this is equivalent to the non-additive name. In particular, if sections appear more than once, the contents are always concatenated. (This is subject to change, additional warnings, etcetera).

for

The =for command paragraph may also be used to create named sections of code, and must appear paired with and ending for statement:

=for literate Descriptive name

...

=for literate .

The stand-alone period is mandatory to signal the end of content collection. The target section is still identified by the "Descriptive name". The for/for is best suited for referenced lines of code, one or multiple lines, because the final blank line before the ending =for will not be included in the code. These sections will be visible with plain perlpod, and are visible when using weave.

The additive syntax also works for sections created with =for.

Section names

Sections named in =begin and =for tags are limited only by perlpod functionality. Each name is referenced in code by placing it within commented identifiers as:

#< Descriptive name >#

Leading and trailing spaces are ignored, but otherwise only the sequence ># would be illegal in a name.

Vertical Spacing

The behavior of single and concatenated begin and for blocks differs with regards to blank lines. Blank lines appear

when               after each reference    between concatenations
using begin/end    yes                     yes
using for/for      no                      no

Consider this example:

=begin literate subs

  sub AAA {
    #< for lines >#
  }

=end literate

=begin literate subs

  sub BBB {
    #< for lines >#
  }

=end literate

=for literate for lines

  # comment 1

=for literate .

=for literate for lines

  # comment 2

=for literate .

The result of tangle will be:

sub AAA {
  # comment 1
  # comment 2
}
  (blank line here)
sub BBB {
  # comment 1
  # comment 2
}
  (blank line here)

For greater control, defined #< blank ># and place it as needed.

Horizontal Spacing

References are included verbatim where they appear, so begin/end blocks are typically not appropriate in the middle of lines. Consider

=begin literate example

  if(#< begin inline >#) { #< for inline ># }

=end literate

=begin literate begin inline

  begin line

=end literate

=for literate for inline

  for line

=for literate .

The result of tangle will be:

if(begin line
) { for line }

Note that #< for inline >##< for inline ># will yield two references without an inside newline, but multiple, concatenated declarations of =for literate will still have a blank line between each.

This permits declarations such as

=for literate header

  =head

=for literate .

to be used in cases such as #<header>#1 Title.

OUTPUT

An output filename may be specified via

=for literate:command target=Module.pm

Multiple targets may be specified by repeating the command, once for each output file. Each target filename must have a defined section =begin literate filename or =for literate filename. Relative and full path specifications are permitted.

Note that the weave command still produces single-file output and does not split documentation into multiple files.

The old syntax will be deprecated: =for literate target:Module.pm

TODO

The following are being considered. No particular priority order here.

todo Weave command is required if the begin/for names are supposed to show up in the POD

The names are clear within the specification, but the generated POD doesn't contain the names. Presumably the generated pod would show something like

< Descriptive name > +=
Content

Basic functionality is provided in weave, but functionality is still being decided.

todo Support =for literate:command import=filename

Documents may appear in sections, and one large POD can become difficult to manage. With a specialized weave command, it would be sensible to support imports.

done Handle multiple output filenames

Multiple target=filename calls can be made.

done First line indentation is removed, to match indentation at the point of reference
done First line indentation applies to every line in the reference
done Inline references

References within lines are expanded normally, with no terminal newline changes.

todo Inline declaration

Support for X<name>code to declare single lines of code within a paragraph.

todo Detect/reject invalid sequences like begin/for, begin/begin, for title/for title
done Investigate colon-prefixed =for :literate command for the command strings.

These are now explicitly rejected. These are meant to denote plain/POD paragraphs according to perlpodspec, which will require additional parsers. This syntax may be used to emit POD into the tangled result in the future.

todo Blank code lines

Blank lines after subroutines have improved with updates to =begin, but there are still cases where it may be worthwhile to support additional filtering instructions during tangling, or when sections are loaded.

This may be entirely the responsibility of a later style tool, but it should be possible to get actual blank lines without having to put those blank lines around the reference. Maybe some #nl or equivalent, which would still look nicer than some lengthy # blank line # type of comment.

Another approach would be, since this is Perl POD, to permit enabling spaces around balanced blocks that are denoted, such as sub.

todo Cross reference

Lexicographic index of all section names etc. (Page numbers seem irrelevant, is it just 1.2.3.4 style subsection numbering?). Possibly leverage `makeindex`, if available.

todo Module pod

(This is possible/solved but not yet documented). How to denote pod that belongs with the output module?

todo Tests

Generally tests will appear in different sections, but it's possible to write a specification where the tests are associated with each section. Unfortunately, for concatenated sections the tests might be more difficult to arrange prior to tangling.

todo Reference wildcards

Support #< Name.* ># to select all matching names, alphabetical order

SEE ALSO

* perlpod

* Pod::Simple

* Wikipedia

* Literate Programming FAQ