From: Dave Storrs [mailto:[EMAIL PROTECTED]] > On Thu, Nov 14, 2002 at 02:29:38PM -0600, Garrett Goebel wrote: > > It is interesting that no one has yet taken the time to > > start defining the terms we're using. > > Good point. I volunteered to be keeper of the glossary a while ago, > but I never actively started creating one. That said, let's make this > the first entry. Comments and constructive criticisms welcomed from > all comers.
I'd prefer to see glossary entries similar the newspaper article format: o catchy title o one paragraph summary o detail Or to restate it in POD: =pod =head1 TERM B<literal> =head1 SYNOPSIS A literal is a represention of a fixed value. =head1 DEFINITION blah blah blah =head1 SEE ALSO L<array of literals>, L<constant>, L<literal array>, L<literal constant>, L<literal value>, L<static constant>, =cut > -------------------- > Term: literal > > Definition: A literal is a way of writing a particular > fixed value. [...] While I enjoy detail, anecdotes, etymology, related concepts, etc. That said, I'd like to see glossary entries written with an extreme economy of words. For example, to nitpick your first sentence. I'd rewrite it as: A literal is a representation of a fixed value. 1) "represent" encompasses write, type, sign, say, etc... 2) "particular" is superfluous I'd also try to limit the entry to the word being defined; refering related topics to their own entries. In this case, I'd put the discussion of literal arrays and array of literals into their own entries, and link to them from the "literal" and "array" entries. > Examples of literals: 7, 3.1415926535897932384, 'Fourscore and seven', > 0xDEADBEEF, b10100011, 'z'. > > Examples of non-literals: $foo, @bar, %baz, jaz() How about however the symbolic constant: my $foo is constant => 1; Do we draw the distinction between a symbolic constant and a literal constant? And what is the difference between a literal, literal constant, and literal value? I'm asking because I really don't know. Are they all short-hand for literal constant value? > NOTES: > > (*) There was a long thread a little while ago on how arrays would be > written. I believe the final decision was that [] was the array > composer, but I'm not sure. Can someone confirm or deny this for me? > (I'll go dig through the archives after I send this, but if someone > knows offhand, it would save time.) No, [] is the explicit list composer Apoc 2, RFC 175: > > explicit list composer: > > [1,2,3] whereas Apoc 2, RFC 009: > > @foo = (1,2,3); > > will supply an unbounded list context to the right side, but > > (@foo, @bar) = (@bar, @foo) > > will supply a context to the right side that requests two > scalar values that are array references. and Apoc 2, RFC 009: > That is, all variables may be thought of as references, not > just scalars. And in that case, subscripts always dereference > the reference implicit in the array or hash named on the left. > > This has two major implications, however. It means that Perl > programmers must learn to write @foo[1] where they used to > write $foo[1]. Which leaves me wondering how do we compose an anonymous array? > First, when I originally started writing these entries, they were > substantially shorter. As I look at them now, I wonder if I haven't > written something that is too long for a glossary entry, and would > better be used for main documentation (or bird cage liner, if you are > unkind)--what do you all think? I agree. I don't mind a lengthy detailed definition and historical or etymological notes... But someone should be able to look at a glossary entry and get the jist of the term as quickly as possible. Which is why I suggested a SYNOPSIS followed by a lengthier DESCRIPTION. > Second, what format should this document be kept in? I know that POD > is the standard, but I feel that POD by itself is a poor fit for a > glossary, since a glossary needs very little presentation but a lot of > structure (for example, you want to group the definition with the > term, and you might want to include attributes--is this a beginner, > intermediate, advanced, or gurus-only concept? Does this term refer > to a core language concept, or is it used primarily in a module? > Which module? And so on....). POD provides enough structure: TERM, SYNOPSIS, DEFINITION, SEE ALSO. And we can certainly provide attributes if needed. > Does anyone strongly object if I keep it in a mixture of XML and POD > (that is, XML containing POD)? If so, what should I keep it in? If > not, does anyone have suggestions on what attributes we should have? POD. TERM, SYNOPSIS|SUMMARY, DESCRIPTION|DEFINITION, SEE ALSO -- Garrett Goebel IS Development Specialist ScriptPro Direct: 913.403.5261 5828 Reeds Road Main: 913.384.1008 Mission, KS 66202 Fax: 913.384.2180 www.scriptpro.com [EMAIL PROTECTED]
