develooper Front page | perl.perl5.porters | Postings from March 2011

Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)

Thread Previous | Thread Next
H.Merijn Brand
March 3, 2011 23:26
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)
Message ID:
On Thu, 03 Mar 2011 23:17:47 -0600, brian d foy <>

> In article <31400.1299175742@chthon>, Tom Christiansen
> <> wrote:
> > Please don't include anything in the standard distribution
> > that tells people they can't use the standard distribution.
> > 
> > If you want to include something in the standard distribution
> > whose entire focus is outside the standard distribution, then 
> > you should bring the thing that is outside, inside.
> The summary: can we reduce the size of the list in perl.pod and replace
> major sections of the docs with new material not based on what's
> already there?
> Some of Dave's work on his new OO tutorial may have come out of a Perl
> heretic talk I gave in Minneapolis around Halloween: 
> The non-core-reference documented has accreted in an unplanned way
> based on whatever people wanted to contribute. It's nice that the
> information is there, but not so nice for the person who has to find it
> or decide what to read. The terse naming scheme and lack of hierarchy
> confuses ordinary people.
> For instance, where do you find the rules and documentation about
> creating variables? It's not in perlvar. While it might make sense to
> us that it's in perlsyn, to the newbie who sees a doc page that says
> "var", that's the first place they'd naturally want to look.
> Similarly, we have swirling around the core reference various quick
> starts, tutorials,  faqs, and so on. 
> So, when it comes to OO, what should the new person read? Although Dave
> doesn't go so far as saying that he wants to replace the various
> non-reference pods, I think that's what should happen. Can we collapse
> perltoot, perlboot, perlobj, perlmod, and perlmodlib into fewer
> documents? Do we have to keep a particular document merely because it
> has always been there evne though no one is updating it?
> The problem, of course, is that you have to treat several topics almost
> simultaneously, including the Perl object system, the package and
> namespace system, references, and distributions, as well as popular
> add-ons from CPAN. Dave also correctly recognizes that most people
> suffer because they don't grasp OO from the start, so they already have
> a disadvantage.
> So, there are various fantasies I have about what the pod/ directory
> could be and how that might help people.
> First, I'd want to organize it:
>      pod/
>           reference
>           tutorials
>           quickstarts
>           faq
>           os-specific
>           changes
>           unicode
>           &c.
> Those are the easy ones, but then we can get a little sloppy. Old docs
> don't have to go away, they just have to find a new home that's out of
> the way. We can also be a bit looser with contributions, like Dave's, 
>      pod/
>           contributed  (third-party, whatever)
>           legacy (old, unsupported, whatever)
> I also hear that we are abandoning the 8.3 filesnames, which some of
> the pod files already ignore, so can we make better names and get rid
> of the useless four characters at the front (except maybe for
> installing man pages):
>      pod/
>           references/
>                variables.pod
>                syntax.pod
>                operators.pod
> If we really wanted to get crazy:
>      pod/
>           references/
>                functions/
>                     open.pod
> With some changes to Pod::Perldoc, we can support the hierarchy with
> the old names as a deprecation cycle:
>      $ perldoc5.16 perlsyn
>      Warning: perlsyn is now syntax, use `perldoc syntax`
> People don't have to know the hierarchy to find the docs with perldoc
> because we'll do that for them. However, when they go to
> or a similar site where they aren't using perldoc,
> they have a leg up.
> Next, in various docs, as appropriate and especially for tutorials, I'd
> put in hints on what the reader should already have looked at, and add
> more cross references. The goal is to reduce the repeated information
> (such as the here docs stuff I just patched in perlfaq and perldiag).
> From there, I'd make a map that shows the relationship of the docs (as
> we say in the Army "A graphical depiction of the earth as seen from
> above"). It would be grand if I could also figure out how to direct the
> person the the right starting point in the map. Although I could do
> that in Inform, maybe, then we'd have to add a z-code runner to core.
> :)
> Some of this begs for a bit more structure. We don't do much with X<>,
> and it would be nice to have structured info that comes out of X<> or
> L<> or maybe something new ( R<reference>? ) that allows us to make
> that map as part of building perl.
> That's enough for tonight.

Enough? :)

I like the idea, but worry about what old-school people like me would
have to type when using "man" instead of "perldoc". What manual pages
would it generate?

 $ man perlvar


 $ man perlrun

are things I still type on a pretty regular basis (regular in the sense
of recurring, not as that I type it twice a day)

I don't like the prospect to have to type

 $ man perl-objects-tutorial-references

or any other long sequence and I *certainly* do not want to go in the
direction that "info" went and make any documentation useless unless
completely printed on dead trees. (That obviously belongs in
hates-software and not here)

So, did you also had ideas about "man" naming schemes?

H.Merijn Brand      Perl Monger
using 5.00307 through 5.12 and porting perl5.13.x on HP-UX 10.20, 11.00,
11.11, 11.23 and 11.31, OpenSuSE 10.1, 11.0 .. 11.3 and AIX 5.2 and 5.3. 

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About