>>>>> "b" == belg4mit <[email protected]> writes:
b> These sound a lot like perltoc to me.
the metadoc isn't anything like that. it is written to explain how to
use the docs. the blurb doc isn't the toc either. it is a written
paragraph with a newbie reader in mind. the toc is autogenerated and
lists the headings of each file but doesn't tell you what the doc is
about, which are related doc, why a newbie should read it, etc.
look at this one:
perlfilter - Source Filters
DESCRIPTION
CONCEPTS
USING FILTERS
WRITING A SOURCE FILTER
WRITING A SOURCE FILTER IN C
Decryption Filters
CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE
WRITING A SOURCE FILTER IN PERL
USING CONTEXT: THE DEBUG FILTER
CONCLUSION
THINGS TO LOOK OUT FOR
Some Filters Clobber the "DATA" Handle
REQUIREMENTS
AUTHOR
Copyrights
that doesn't even explain what a source filter is? would a newbie get
that from the toc? and the fact that source filtering is frowned upon by
most because of the inherent problems it has is not mentioned. i
wouldn't point a newbiew to the toc without guidance.
also the toc is 16k lines long!! how many newbies will scan that? a
blurb doc as i envision it will be about 1-2k lines which is very readable.
uri
--
Uri Guttman ------ [email protected] -------- http://www.sysarch.com --
----- Perl Code Review , Architecture, Development, Training, Support ------
--------- Gourmet Hot Cocoa Mix ---- http://bestfriendscocoa.com ---------
_______________________________________________
Boston-pm mailing list
[email protected]
http://mail.pm.org/mailman/listinfo/boston-pm
