/ 
Pod-Literate-0.0.2
/ Pod::Literate

NAME

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

VERSION

Version 0.0.2

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.

Section declaration versus addition

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

Hidden sections

When weave is provided, both of begin and for sections will become visible. There may be some benefit to having hidden sections that still generate code.

Unused sections

Unused sections may become failures, warnings, etc.

Commands

Commands like literate target:name might change. Considering :literate for these.

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 behave different within perlpod, where the =begin paragraphs will be hidden, but both declarations are visible with the current weave command.

begin and end

The begin and end command paragraphs are used to create sections that are hidden in perlpod (but still visible during a weave operation), 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.

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 denotes sections that are not hidden in perlpod, nor during a weave operation. The ending of a for section uses a period:

=for literate Descriptive name

...

=for literate .

At this time the period is mandatory and signals the end of content collection.

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.

OUTPUT

At this time, a single output file is supported per specification:

=for literate target:Module.pm

Relative and full path specifications are permitted. (Expect this to support multiple file output in the future).

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

todo Handle multiple output filenames

The target:filename can simmply set the output and all subsequent sections will be collected therein. If another filename is encountered, the scanner will start putting sections there. With an import statement, the filenames would be fairly well scoped, and perhaps import should explicitly scope any set filename.

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
todo Inline references

Most work has been focused on standalone references. What is the behavior of { named reference } when the reference is a single line? Multiline?

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
todo Investigate colon-prefixed =for :literate command for the command strings.
todo Blank code lines

Blank lines before/after subroutines, for example, are not straightforward to specify. Inside =for blocks, those would violate podchecker which expects no whitespace-only lines. It may be this is 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

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