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
From:
H.Merijn Brand
Date:
March 3, 2011 23:26
Subject:
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)
Message ID:
20110304082644.3715881f@pc09.procura.nl
On Thu, 03 Mar 2011 23:17:47 -0600, brian d foy <brian.d.foy@gmail.com>
wrote:
> In article <31400.1299175742@chthon>, Tom Christiansen
> <tchrist@perl.com> 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:
>
> http://www.slideshare.net/brian_d_foy/perldocs
>
> 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
> perldoc.perl.org 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
and
$ 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 http://tux.nl Perl Monger http://amsterdam.pm.org/
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.
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Thread Previous
|
Thread Next