Use perltodo(1) to find Perl's live to-do list

You will use the installed perltodo(1) documentation to reach Perl's maintained to-do list, then verify the destination before relying on it. On this machine the reference comes from perl-doc version 5.38.2-3.2ubuntu0.6. Allow about five minutes. You need a shell and a network connection only if you want to open the current list online.

There is one easily missed detail: perltodo is a manual page, not a shell program. It does not accept options, display the list itself or change Perl. The useful result is the official repository URL recorded by the manual.

1. Confirm that the reference is installed

Ask the manual database for the page. This is an ordinary, read-only command and does not need 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 that no manual entry exists, 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.

Checkpoint: if man -f perltodo returns the entry, continue. If it does not, stop here and fix the documentation installation before trying to follow a remembered URL.

2. Read what perltodo(1) actually provides

Open the page in the normal pager:

$ man perltodo

Its name and description say that it links to Perl's to-do list. The page explains that the old list used to be shipped in perltodo, but that an installed snapshot would become stale. The maintained copy is 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. 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 the page with a tool you already trust:

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

The command launches your desktop's configured browser and normally prints no useful output. If you are 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 the contents can change as maintainers and contributors update the file.

For a text-only check, download nothing and just test that 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 finish 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 affect 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:

• perltodo(1) is the local pointer shipped by perl-doc.
• Porting/todo.pod in the Perl repository is the changing source of the 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 task list. Do not edit the compressed manpage to update it: package-managed files are overwritten by upgrades, and the manual deliberately points to the maintained upstream copy.

5. Diagnose the common wrong turns

If you try to execute the name, 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 associated with this reference.

If man perltodo opens a page but the URL cannot be reached, the local documentation is still valid as a pointer. Check the exact address shown by the installed page and 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 has priority.