lichtkind

At TPC in Amsterdam I gave 2 lightning talks under the title perldoc -O. It was a questionary for the attendance which should give me some orientation which feature to prioritize or how to modify them best. I also spoke and mailed with all people I deemed relevant and want now to lay out the feature set I want to achieve with the rewrite.

1. WHY

perldoc works and is stable - why touch it? Well one reason for its stability: very few people are able to add features. A good test suite is also lacking and the docs for perldoc missing some bits here and there. Last not least the input parser is very generous. My plan is to reject invalid input and not just ignore it (current state). This will not break anything unless you got used to add random letters after a valid input.

These goals are the first stage i navigate toward, because by then i should know all that is to be know about the problem, I didn't changed anything yet and we have at least a future proof version. This prototype will be certainly dismissed.

2. HOW
Without explaining here my complete programming (TM) in all glory: it's basically a method to modularize the development in a way that its still joy, productive and allows to measure progress. I will use here a simplified version of what I do with Kephra. The first prototype or a collection of them will give us all the bits of code that do what perldoc is currently doing (minus the strange param parsing) , but in manageable and identifiable portions. Just after than I want to structure them in several modules so the single tasks of finding the POD, searching the content or parsing the input are not only separated but also some are of potential use for other tools.

3. Indexing
One of the issues i have with perldoc you cant find a specific information quickly. perlfunc and perlvar are nice but why we have on perldoc.org and extra page that lists just the content? Because there is a need for that. And I want that too in perldoc (with full signatures and some references to other perdoc pages). Also pragmas and [core- and other] modules could use their own index. Don't forget that perldoc perl is also such an index page.

Another issue for supporting IDE and other tools is to give a numbered list of all headings of the requested pod page. Together with another perlpod - parameter that gives me just the chapter with that number not just enables such tools but also a new way to use perldoc from the command line (something with curses?).

4. Search
Even slightly interested people liked the idea to have searchable pod pages. Basically have not only a -q that searches the FAQ but a universal search flag that searches in the specified domain (FAQ, variables, functions, tuts, addons, etc). Damian and me agreed that it is important to not only search in plain text but also in headings and indexes. Of course we need to add some sensible X<....> - Tags into the pages for that, so we have keywords to search for. In the end is search in headings what perldoc -f kinda does, why don't make the feature universally accessible. And if we already talk about this why not make MetaCPAN one domain we can search in. This might slow things down but you don't have to use it and it would probably shove it in a addon - module anyway.

5. Alltogether
A special request of Damian was it to introduce the -A flag, which looks up all pages. One lookup that crawls the -f domain, the -a , -v and so forth and gives me all results in on doc (that gets normally paged anyway).

6. Levenstein
Because I already implemented this last year in Perl, why not make the page requests slightly fault tolerant. Man I just love the Perl 6 error messages: did you mean this ...?

7. Addons
There are excellent additional docs for Perl 5 like choroba's Syntax::Construct or hopefully my planned Module perlsum. If you like such content, why not install such modules and automatically have them accessible under their own perldoc flag, to be able to see their headers or search them or have their contribution listed also when you use the -A flag. Its also something -L kinda already does. I just want to press the most benefit out of its mechanics.

If you have any other ideas please comment or write me a mail.

Thanks a lot.