Michael G Schwern wrote:
>
> On Tue, Aug 01, 2000 at 08:26:22PM -0700, Tim Conrow wrote:
> > My problem with X<> it is that it's disruptive to the readability of
> > the text if it's embedded and used too much, as it might well be for
> > indexing. I was trying to navigate a way around that problem.
>
[Good comments snipped]
> Any artificial list of keywords attached to a document, as you
> originally suggested, is next to useless as it will probably not be
> maintained for the same reasons which code and distant documentation
> drift aparet. And will also not be a valid representation of the
> actual text. Its the HTML <META> keyword syndrome. Whether
> deliberately or on purpose, you will subtly lie about the contents of
> your document to make it seem like there is more there.
Yes, the more I've thought about it, the less useful improved indexing seems,
since it is unlikely to be well maintained, and mandating its maintenance is a
barrier to documenting; not something we want to do. Which is why you haven't
seen an RFC from me on the subject.
The docs are copious and detailed, but their very size and completeness (and
subsequent complexity) makes them imposing and hard for newcomers to grasp and
navigate. Some topics are scattered or not where you'd expect. Cross linking
among the docs seems necessary to me. 'perldoc -q ...' and clever use of 'tcgrep
-p ...' can help, but I think we should strive for something better for a shiny
new perl.
Am I alone in having this view, and seeing its value to the QA process?
Here's another clay pigeon I'll throw into the air. Fire at will.
Instead of index entries scattered around the docs, how 'bout a centralized
topics index maintained separately, where a doc author could freely add a topic,
or add to the list of references of an extant topic. Something like:
topic refs annotation (optional)
------------------------------------------------------------------------
context ref1 good overall tutorial
ref2 ... and lists and arrays
ref3 ... and functions and operators
lists ref1 constructing
<context.ref2> ... and context
ref2 ... vs. arrays vs. hashes
hashes ref1,ref2,ref3 basics
ref4 internal implementation
arrays
etc.
With a browser one could follow each reference for a given topic and see the
whole of what the perl docs had to say on the matter. Each reference could be
tagged as for a beginner, intermediate, or advanced user, or for an internals
developer. I know the GNU info docs are often accompanied by concept indicies,
but they are very low level and do not produce a coherent picture of broad
topics. Perhaps Perl+Pod can do better.
I think a central clearinghouse like this could be valuable not only to
beginners, but for perl6 designers and implementors as they put pieces together.
It's a way to see the forest for the trees. Maintenance might be easier (I posit
without evidence) for each author, but someone (a document pumpking?) would have
to be responsible for the integrity of the topics list. There'd also have to be
a way for the references to point to a location in a document that would survive
the doc being revised.
I can certainly see this being alot of trouble, but I can also see alot of value
in it.
--
-- Tim Conrow [EMAIL PROTECTED] 626-395-8435
