Use perltodo(1) to Find Perl's Live To-do List

perltodo(1) will not show you a to-do list: it just points you at one, and that pointer is the whole trick. This guide gets you from the installed page to Perl's actual maintained wishlist, so you are not reading a copy that went stale years ago. On this machine the reference comes from perl-doc version 5.38.2-3.2ubuntu0.6. Allow about five minutes, plus a browser if you want to open the current list online.

The easily missed part: perltodo is a manual page, not a shell program. It takes no options, shows no list itself, and changes nothing about Perl. What it gives you is the repository URL the manual records as current.

1. Confirm that the reference is installed

Ask the manual database for the page. This is an ordinary, read-only command that needs no sudo:

$ man -f perltodo
perltodo (1)          - Link to the Perl to-do list

The exact spacing can vary with your man implementation; the important parts are the name and section 1. If the command reports no manual entry, install the documentation package through your normal package-management process, then repeat the check. Do not infer that the Perl interpreter is broken: perl-doc is a separate documentation package on this system.

2. Read what perltodo(1) actually provides

Open the page in the normal pager:

$ man perltodo

Its name and description say it links to Perl's to-do list. The page explains that the old list used to be shipped inside perltodo itself, but an installed snapshot would go stale. The maintained copy lives in the Perl 5 git repository, under Porting/todo.pod.

To inspect the compressed file without a pager, use the installed source path directly:

$ zcat /usr/share/man/man1/perltodo.1.gz | col -b | sed -n '/^\.SH NAME/,$p'
\.SH NAME
perltodo \- Link to the Perl to-do list

The rendered man perltodo view is easier to read. The direct command is a useful diagnostic when the manual pager or its database is behaving strangely, but it is still only reading local documentation.

3. Open the current Perl list

Use the URL named by the manual in a browser, or fetch it with a tool you already trust:

$ xdg-open https://github.com/Perl/perl5/blob/blead/Porting/todo.pod

This launches your desktop's configured browser and normally prints no useful output. Working over SSH? Copy the URL into a browser on a machine with network access instead. The blead branch is Perl's development branch, so its contents can change as maintainers and contributors update the file.

For a text-only check, download nothing and just confirm the official page responds:

$ curl --fail --location --silent --show-error \
    https://github.com/Perl/perl5/blob/blead/Porting/todo.pod \
    > /tmp/perl-todo.html
$ test -s /tmp/perl-todo.html && echo 'received the Perl todo page'
received the Perl todo page

This writes a temporary copy under /tmp, not a Perl source tree or system directory. Remove it when you are done if it contains material you do not want to keep:

$ rm -- /tmp/perl-todo.html

That removal is irreversible for the temporary copy, but it does not touch the upstream repository or your local Perl installation. If curl fails, check the network, proxy and certificate configuration rather than treating an unreachable page as an empty to-do list.

4. Read the list without mistaking it for a release plan

The repository file is a list of wishes and possible work for Perl. It is useful for finding areas where help may be welcome, but a listed item is not automatically an assigned issue, a promised feature or a supported command. The current file also points readers towards Perl's issue tracker and asks prospective contributors to contact the Perl porters community to avoid duplicating work.

Keep the two locations separate in your notes:

• The local pointer. perltodo(1) is shipped by perl-doc and never changes between package upgrades on the same release.
• The changing source. Porting/todo.pod in the Perl repository is the actual, live list.

If you are recording a task for a project, save the date and the branch or commit you read: a later visit to blead may show a different list. Do not edit the compressed manpage to update it either; package-managed files are overwritten by upgrades, and the manual deliberately points to the maintained upstream copy instead.

5. Diagnose the common wrong turns

Try to execute the name and the shell will usually fail, because no perltodo binary is installed:

$ command -v perltodo
$ printf '%s\n' "$?"
1

An empty result from command -v is expected here. Use man perltodo, not perltodo --help: there is no documented option set, configuration file, daemon, service or elevated operation attached to this reference.

If man perltodo opens but the URL cannot be reached, the local documentation is still valid as a pointer. Check the exact address the installed page shows, then use a browser or HTTP client with working network access. If a future package version points somewhere different, follow that installed page and record the new version rather than assuming this example still has priority.