Ticket #292 (closed cage: fixed)

Opened 13 years ago

Last modified 10 years ago

[CAGE] Update all Pod documentation to use sane, modern headings

Reported by: allison Owned by: whiteknight
Priority: normal Milestone:
Component: docs Version: trunk
Severity: medium Keywords: newbie
Cc: Language:
Patch status: Platform: all

Description

The Pod documentation in the repository currently uses a crufty old Perl 5 style, that gives document titles using "=head1 NAME" blocks, and breaks up the file into multiple "=head1 ALLCAPS" sections. Aside from making absolutely no sense outside the Perl tradition, this old style generates truly horrible html and man formatted documents, which are the primary way most people will read them.

- Modernize all files to use a single "=head1" for each document (the title of the document).

- Don't include the file name in the documentation (either they're reading the file in the source tree and so know the file path already, or they aren't and don't care about the file path).

- Demote subsections so they are all "=head2" or below (preserving the section hierarchy, so "=head3" changes to "=head4", etc).

- Use title case in all section titles ("Description" instead of "DESCRIPTION").

See r36470 for an example.

Change History

  Changed 13 years ago by jkeenan

  • owner set to jkeenan
  • status changed from new to assigned

  Changed 13 years ago by jkeenan

Work begun in update_pod branch. Note: as far as podchecker is concerned,

=head5 Some Heading

... is not permitted. Changed all instances to

=item *

See r36573. More to come.

kid51

in reply to: ↑ description ; follow-up: ↓ 4   Changed 13 years ago by jkeenan

I have taken this ticket and been working on it in a branch for the past week. I began by first investigating what tests we currently have for POD and how we identify files which merit examination for the validity or quality of their POD. I've refactored a lot of that code, but I think a number of issues Allison raises merit further discussion before proceeding.

The Pod documentation in the repository currently uses a crufty old Perl 5 style, that gives document titles using "=head1 NAME" blocks, and breaks up the file into multiple "=head1 ALLCAPS" sections. Aside from making absolutely no sense outside the Perl tradition, this old style generates truly horrible html and man formatted documents, which are the primary way most people will read them.

There are three issues here.

1.

Is the Perl 5 style of documentation as 'crufty' as claimed above? Or is it simply a matter of individual taste and our desire to differentiate Parrot from Perl? I've been following Perl for nine years and contributing documentation in the Perl 5 format to CPAN for seven years. In that time I can't recall much discussion -- either complaints or praise -- about the HTML or man pages generated from POD. So if we're going to head in a new direction, we should probably have more discussion about what we find specifically objectionable in the current practice.

2.

Even if we agree that our documentation should go in a different direction in the future, we must recognize that we currently have different standards in different Parrot Design Documents. docs/pdds/pdd00_pdd.pod states that PDDs must follow the style exemplified by docs/pdds/pdd_template.pod. This is the style requested by Allison -- unique =head1; title-case all headings; etc. -- in this TT and implemented in r36470.

docs/pdds/pdd07_codingstd.pod, however, we call for documentation in Developer files to follow a more traditional format:

The POD documentation should follow the standard POD layout:
[snip]
=item NAME

src/foo.c - Foo

=item SYNOPSIS

When appropriate, some simple examples of usage.

=item DESCRIPTION

... i.e., all upper-case headings. Most source code files that have POD at all have it in this format. We would have to revamp a lot of files to move them from one format to another, and we should evaluate whether that's the best use of our time. Perhaps we could live with one approach for the PDDs and another for the source code. Which leads to the third issue ...

3.

Regardless of which standard we have or whether we live with one standard or two, we must have a way of identifying files which fail to conform to that POD standard before we can recruit people to fix them. We currently have two tests (neither of which runs as part of make test) which evaluate files for POD in various ways. t/doc/pod.t does two things: It checks for the syntax of files with POD and it has a TODO-ed test which checks whether files with POD which have a DESCRIPTION heading have any content in that section. t/codingstd/pod_todo.t checks for the presence of the strings TODO, FIXME and XXX in files' POD. (I propose to move t/doc/pod.t into t/codingstd so that we have all our POD-checking tests in one directory.)

Both of these test files use CPAN distribution Pod::Simple to identify files with POD and extract their DESCRIPTION sections. (Pod::Simple only went in to the Perl core at 5.9, so it's one of those distributions currently sitting inside our repository so that people who build Parrot with 5.8 have it available.) But there's a problem here: AFAICT, when Pod::Simple tries to extract POD sections, it is hard-coded to look for all upper-case headings:

sub get_description { shift->_get_titled_section(
   'DESCRIPTION',
    max_token => 400,
    max_content_length => 3_000,
   @_,
) }

(This code is found in Pod::Simple::PullParser.) So when you run prove -v t/doc/pod.t, you get a list of over 500 files which have empty DESCRIPTION sections -- including all of those PDDs where DESCRIPTION has been changed per our first standard to Description.

So, if we have any POD standards at all, then we must have a way of identifying files that fail to meet that standard. (Any disagreement there?) If we want that standard to be anything other than, or in addition to, the traditional POD format, then we will have to develop code to replace or subclass Pod::Simple that we can use to identify those files. We should discuss whether the time and effort required to that is worth it.

So there's a lot more work involved in this ticket than may have first been evident. Comments?

Thank you very much.
kid51

in reply to: ↑ 3   Changed 13 years ago by jkeenan

Replying to jkeenan:

I received no comments, so I contented myself with merging into trunk tonight the work I had completed three weeks ago. Cf.: r37191.

Anyone else who has an idea how to approach these issues is welcome to take the ticket.

Thank you very much.
kid51

follow-ups: ↓ 7 ↓ 8   Changed 13 years ago by allison

1. The Perl 5 conventions were developed for Perl more than 10 years ago. It made sense for the time and the context. But, a lot has changed since then. The fact that we're using Pod syntax (which is really just a very lightweight markup language) doesn't mean we have to also adopt all the Perl 5 conventions. We'll keep what makes sense for us, but we aren't (and shouldn't be) chained to Perl 5 culture.

2. Good point. I updated the coding standards after I first saw this ticket, in, let's see... r37253.

3. Yes, Pod::Simple follows the Perl 5 conventions slavishly (I'd even go so far as to say "stupidly", which I can do without insulting anyone since I'm the maintainer, and therefore it's my decision to keep it focused on Perl 5). But, Pod::Simple will also be deprecated and replaced with the PGE-based Pod parser as soon as we finish it. In the mean time, we're pretty safe either subclassing Pod::Simple (which we already do in several places) or just not testing for description sections.

You probably didn't mean r37191, since that was a commit by coke. Perhaps you meant r37193 which seems to be a large set of Pod-related fixes made by you.

  Changed 13 years ago by allison

  • milestone 1.0 deleted

in reply to: ↑ 5   Changed 13 years ago by jkeenan

Replying to allison:

You probably didn't mean r37191, since that was a commit by coke. Perhaps you meant r37193 which seems to be a large set of Pod-related fixes made by you.

Yes, r37193 was what was intended. thanks.

in reply to: ↑ 5   Changed 13 years ago by jkeenan

Replying to allison:

In the mean time, we're pretty safe either subclassing Pod::Simple (which we already do in several places) or just not testing for description sections.

Could you point me to one of the places where we do such subclassing? Also, am I likely to have to subclass anything beyond Pod::Simple::PullParser (the only location where I could find the string DESCRIPTION sought for)?

  Changed 13 years ago by coke

Added this ticket # to t/codingstd/pod_description.t's TODO so folks don't mistakenly try to make the test pass. (r37889)

  Changed 13 years ago by allison

Our Parrot::Doc::* modules subclass Pod::Simple.

But, on the whole, I'd rather not put effort into writing Pod parsers in Perl 5. We're trying to move toward less Perl 5 code in the repository.

Oh, BTW, I found the source of the Perl 5 Pod-style. They selected their headings to exactly match the required headings for manpages (which made sense 20 years ago when that was the primary output from the Pod sources).

  Changed 12 years ago by coke

Note, this ticket supersedes this other  RT.

  Changed 12 years ago by jkeenan

In the course of working on TT #1301, I encountered some files where the Pod DESCRIPTION section consisted of nothing more than a reference to the RT item which this ticket replaced. That, in turn, led me to turn my attention to the long-neglected t/codingstd/pod_description.t, which was showing more than 300 files which lacked a Pod DESCRIPTION section or content therein.

So I have begun working my way through that list. However, in order to get certain files cleared off the failing list, I have had to make them conform to the Pod style which Allison ultimately wants replaced. My belief is that we are better off going ahead and checking each file reported as failing to see whether it has content that could be put into a DESCRIPTION section and do so -- and worry about new Pod styles later. So that means that in certain cases I will be replacing:

head1 Description

with

head1 DESCRIPTION

and so forth.

kid51

  Changed 12 years ago by coke

On Sat, Nov 21, 2009 at 3:14 PM, Parrot <parrot-tickets@lists.parrot.org> wrote:
> #292: [CAGE] Update all Pod documentation to use sane, modern headings
> ---------------------+------------------------------------------------------
>  Reporter:  allison  |       Owner:  jkeenan
>     Type:  cage     |      Status:  assigned
>  Priority:  normal   |   Milestone:
> Component:  docs     |     Version:  trunk
>  Severity:  medium   |    Keywords:
>     Lang:           |       Patch:
>  Platform:  all      |
> ---------------------+------------------------------------------------------
>
> Comment(by jkeenan):
>
>  In the course of working on TT #1301, I encountered some files where the
>  Pod `DESCRIPTION` section consisted of nothing more than a reference to
>  the RT item which this ticket replaced.

That way lies madness. If you find those and cannot come up with a
sufficient DESCRIPTION, please remove the placeholder and skip it in
the codingstd test; (We went through this same dance on function
documentation)

> That, in turn, led me to turn my
>  attention to the long-neglected ''t/codingstd/pod_description.t'', which
>  was showing more than 300 files which lacked a Pod `DESCRIPTION` section
>  or content therein.
>
>  So I have begun working my way through that list.  However, in order to
>  get certain files cleared off the failing list, I have had to make them
>  conform to the Pod style which Allison ultimately wants replaced.  My
>  belief is that we are better off going ahead and checking each file
>  reported as failing to see whether it has content that could be put into a
>  `DESCRIPTION` section and do so -- and worry about new Pod styles later.
>  So that means that in certain cases I will be replacing:
>  {{{
>  head1 Description
>  }}}
>  with
>  {{{
>  head1 DESCRIPTION
>  }}}
>  and so forth.
>
>  kid51
>
> --
> Ticket URL: <https://trac.parrot.org/parrot/ticket/292#comment:12>
> Parrot <https://trac.parrot.org/parrot/>
> Parrot Development
> _______________________________________________
> parrot-tickets mailing list
> parrot-tickets@lists.parrot.org
> http://lists.parrot.org/mailman/listinfo/parrot-tickets
>



-- 
Will "Coke" Coleda

  Changed 12 years ago by NotFound

Even more: if no one is able to write a description of a file, consider deleting it.

  Changed 12 years ago by coke

  • status changed from assigned to new
  • owner changed from jkeenan to coke

  Changed 12 years ago by coke

(taking ticket per jkeenan's previous offer)

  Changed 11 years ago by cotto

  • keywords newbie added

  Changed 11 years ago by coke

  • owner coke deleted

  Changed 11 years ago by whiteknight

  • owner set to whiteknight

  Changed 10 years ago by whiteknight

  • status changed from new to closed
  • resolution set to fixed

I can't see anything in this ticket that I think is still undone and worthwhile, so I'm closing it. If we have specific issues with our documentation we can open specific tickets to address them.

Note: See TracTickets for help on using tickets.