NAME

tools/dev/extract_file_descriptions.pl - Extract descriptions from files

SYNOPSIS

    % perl tools/dev/extract_file_descriptions.pl [--plus-misses] [files ...]

DESCRIPTION

This script extracts descriptions from the Parrot source files. If no files are specified on the command-line then the files worth describing will be found recursively from the current directory.

Options

--plus-misses

This creates a second section, with the heads of any files which had familiar types, but from which descriptions were not obtained.

TODO (RT#46903)

• Given a directory argument, should recursively descend.
• Should create descriptive hashes earlier, before files are filtered. So one can skip, say a binary file, but still have it listed in the output. For instance, it is nice to see where the .pbc's land.
• Allow indescribable heads to be mixed in with rest, for when exploring a location is more important than big-picture browsing.
• Is absense of "[...]"s in the indescribable listing a ui consistency violation?
• Fragment describe_file() - it shouldn't both `cat` and dispatch on file suffix.
• Finish making this usable as a library.
• It would be nice to have a ParrotSourceFile class of course. ;) (a jest - sort of.)
• Misc: rationalize indent; clarify desc emptiness contract; review readability of intra-comment blank line elimination; pod handling;