Re: Synposis 26 - Documentation [alpha draft]
On October 7th Damian Conway wrote: Before Christmas, as promised! [DRAFT] Synopsis 26 - Documentation Thank you for that, Damian! Apologies for taking a while to respond, but I wanted to leave reading the document until I had a sufficient chunk of time to do it justice. And I was very impressed. One quibble: To include named Unicode or XML entities, use the CE code. If the contents are not a number, they are interpreted as an upper-case Unicode character name, or as a lower-case XML entity. For example: Perl 6 makes considerable use of Elaquo and Eraquo. I think the only standard XML entities are Clt;, Cgt;, and Camp;. Particular XML languages can define further entities which use that syntax, but they aren't included by default. However, the examples you give are HTML entities, defined in the HTML 4 spec: http://www.w3.org/TR/REC-html40/sgml/entities.html Smylers
Re: Synposis 26 - Documentation [alpha draft]
On Oct 16, 2006, at 2:51 PM, Smylers wrote: ... Perl 6 makes considerable use of Elaquo and Eraquo. I think the only standard XML entities are Clt;, Cgt;, and Camp;. Particular XML languages can define further entities which use that syntax, but they aren't included by default. The default entities are Clt;, Cgt;, Camp;, Capos;, and Cquot;. So glad I could contribute that. - Danny
Re: Synposis 26 - Documentation [alpha draft]
Smylers pointed out (and Danny Brian confirmed): The default entities are Clt;, Cgt;, Camp;, Capos;, and Cquot;. I *knew* there was a good reason I shun XML! ;-) Clearly five entities is Inot going to suffice. The synposis now reads: To include named Unicode or XHTML entities, use the CE code. If the contents are not a number, they are interpreted as an upper-case Unicode character name, or as a lower-case XHTML entity. For example: Thanks for that. Damian
Re: Synposis 26 - Documentation [alpha draft]
Brent wrote:
I've probably been hanging around Web standards nazis for too long,
but can we get a separate code to mark the title of a document that
can't be linked to (say, a book) along the lines of HTML's cite tag?
Hmm. Maybe. Care to nominate a letter for that? C, I, T, and E are
all take already. ;-)
Actually, a couple more link schemes could probably handle my previous
request:
LPerl 6 and Parrot Essentials|urn:isbn:059600737X
LParrot Magic Cookies in The Perl Review|urn:issn:1553667X/3/0#11
Why wouldn't that just be:
LPerl 6 and Parrot Essentials|isbn:059600737X
LParrot Magic Cookies in The Perl Review|issn:1553667X/3/0#11
Oooh, transclusion--shiny. Perhaps the pipe character can be used to
provide alternative text:
PSee standard copyright terms in the distribution.
|file:/shared/docs/std_copyright.pod
I like it. The only concern would be that, everywhere else that a pipe is
valid, the LHS is rendered instead of the RHS. Here it would be reversed.
Arguably, by that measure, it ought to be:
Pfile:/shared/docs/std_copyright.pod
|See standard copyright terms in the distribution.
Of course, you could always argue that the LHS is the text side and the RHS
the URL side. Hm. I need to think about that a little more.
Also, what about non-textual files? If I type
Phttp://www.perlfoundation.org/images/onion_64x64.png, will an onion
appear in my Pod document? That would obviate custom =Image
directives.
That would depend on the renderer. The parser will certainly accept it. I'd
expect that renderers that can render images would probably do so.
Perldoc provides a mechanism by which you can extend the syntax and
semantics of your documentation notation: the C=use directive.
Um...how can this be made to work? Are renderers going to have to
know about every possible plugin? Are plugins going to have to know
about every possible renderer? Will dogs and cats be living together?
To answer your questions in order: Easy. No. No. Hell no!
The parser doesn't change when you extend syntax and semantics. Plugins can
only change the syntax of the *contents* of a new block type, not the way the
parser parses those blocks. For example, to get Markdown syntax and semantics,
you write:
=use Perldoc::Plugin::Markdown
=begin Markdown
*Markdown* syntax and semantics _in this block_
=end Markdown
The parser would still parse the Markdown block to create a
Perldoc::Block::Markdown object, even if you hadn't C=use'd the module. The
C=use merely allows the parser and/or renderer to load the class definition
of the Perldoc::Block::Markdown class, so that the object can be constructed
correctly (and, presumably, the contents of the block can be interpreted
meaningfully).
So, in other words, the syntax of Pod blocks is invariant, allowing the parser
to reduce Pod to a standard internal object stream, which each renderer (and
any plug-in extension) can do with as it will.
I obviously need to make those points clearer in the synopsis. Thanks.
C=config specifications are lexically scoped to the block in which
they're specified.
=config head3 :numbered
=cut
There is no C=cut in Perl 6. And in your example it wasn't needed, BTW,
since Pod reverts to ambient code after each block unless you're nested inside
a =begin...=end pair.
method foo($bar, $baz) {
...
}
=head3 Cfoo(RbarC, RbazC)
...
Is that =head3 numbered, or is it in a different lexical scope?
Assuming the =cut wasn't there, the =head3 would be numbered, since you'd be
in the same lexical scope. Lexical scopes are defined by =begin..=end pairs,
not by the chunking of Pod within ambient code.
(Actually, I don't see any reference to =cut in this spec. Is it
still there or not?)
Not. :-)
Damian
Re: Synposis 26 - Documentation [alpha draft]
Tim Bunce wrote: That's going to cause pain when people using older parsers try to read docs written for newer ones. Would a loud warning plus some best-efforts fail-safe parsing be possible? Indeed. And that's a important use-case. But best-effort is difficult when you're talking about future-compatibility of core constructs, which these are supposed to be. I guess best-effort for uppercase (semantic) mark-up is just to map: =begin UNKNOWN mumble mumble mumble =end UNKNOWN to: =head1 UNKNOWN =begin para mumble mumble mumble =end para But it's harder to see how to cope with unknown all-lower directives: =begin frobnication ... =end frobnication =for franistat =wassname Especially the last of those, since it might be either an abbreviated block or a pure directive. I suspect that these should either still be fatal, or they should warn-and-ignore. Damian
Re: Synposis 26 - Documentation [alpha draft]
Jonathan Lang wrote: If I understand you correctly, the pain to which you're referring would come from the possibility of a name that's reserved by the newer version of Pod, but not by the older version. Wouldn't the simplest solution be to let a Pod document announce its own version, much like Perl can? That would presumably be: =use 6.0.2 Though it's not quite an exact analogy. If a Perl interpreter isn't recent enough, it can't really fall back on best attempt to execute a program. Code is either valid or unusable. For documentation, even if you don't know how to interpret a particular mark-up, you can always just display it as raw text and the reader can still get most of the benefit of it. It's hard to imagine a circumstance in which a refusal to render Pod: Perldoc v6.0.2 required--this is only v6.0.1, stopped at S26.pod, line 1 would be preferable to actually rendering that Pod, no matter how badly. Damian
Re: Synposis 26 - Documentation [alpha draft]
On 10/7/06, Damian Conway [EMAIL PROTECTED] wrote:
The CI formatting code specifies that the contained text is
to be set in an Iitalic style
I've probably been hanging around Web standards nazis for too long,
but can we get a separate code to mark the title of a document that
can't be linked to (say, a book) along the lines of HTML's cite tag?
=begin item :term('Chttp: and Chttps:')
A standard URL. For example:
This module needs the LAME library
(available from Lhttp://www.mp3dev.org/mp3/)
=end item
=begin item :termCfile:
A filename on the local system. For example:
Next, edit the config file (Lfile:~/.configrc).
=end item
=begin item :termCman:
A link to the system man pages. For example:
This module implements the standard
Unix Lman:find(1) facilities.
=end item
=begin item :termCdoc:
A link to some other Perldoc documentation, typically a module or core
Perl documentation. For example:
You may wish to use Ldoc:Data::Dumper to
view the results. See also: Ldoc:perldata.
=end item
Actually, a couple more link schemes could probably handle my previous request:
LPerl 6 and Parrot Essentials|urn:isbn:059600737X
LParrot Magic Cookies in The Perl Review|urn:issn:1553667X/3/0#11
If a renderer cannot find or access the external data source for a
placement link, it must issue a warning and render the URL directly in
some form. For example:
=begin indent
BCOPYRIGHT
See: /shared/docs/std_copyright.pod
BDISCLAIMER
See: http://www.megagigatera.com/std/disclaimer.txt
=end indent
Oooh, transclusion--shiny. Perhaps the pipe character can be used to
provide alternative text:
PSee standard copyright terms in the
distribution.|file:/shared/docs/std_copyright.pod
Also, what about non-textual files? If I type
Phttp://www.perlfoundation.org/images/onion_64x64.png, will an onion
appear in my Pod document? That would obviate custom =Image
directives.
Perldoc provides a mechanism by which you can extend the syntax and semantics
of your documentation notation: the C=use directive.
Um...how can this be made to work? Are renderers going to have to
know about every possible plugin? Are plugins going to have to know
about every possible renderer? Will dogs and cats be living together?
C=config specifications are lexically scoped to the block in which
they're specified.
=config head3 :numbered
=cut
method foo($bar, $baz) {
...
}
=head3 Cfoo(RbarC, RbazC)
...
Is that =head3 numbered, or is it in a different lexical scope?
(Actually, I don't see any reference to =cut in this spec. Is it
still there or not?)
--
Brent 'Dax' Royal-Gordon [EMAIL PROTECTED]
Perl and Parrot hacker
Re: Synposis 26 - Documentation [alpha draft]
On Thu, Oct 12, 2006 at 02:55:57PM +1000, Damian Conway wrote: Dave Whipp wrote: I'm not a great fan of this concept of reservation when there is no mechanism for its enforcement (and this is perl...). What makes you assume there will be no mechanism for enforcement? The standard Pod parser (of which I have a 95% complete Perl 5 implementation) will complain bitterly--as in cyanide--when unknown pure-upper or pure-lower block names are used. That's going to cause pain when people using older parsers try to read docs written for newer ones. Would a loud warning plus some best-efforts fail-safe parsing be possible? Tim. The whole point of reserving these namespaces is not to prevent users from misusing them, but to ensure that when we eventually get around to using a particular block name, and those same users start screaming about it, we can mournfully point to the passage in the original spec and silently shake our heads. ;-) Damian
Re: Synposis 26 - Documentation [alpha draft]
On Thu, Oct 12, 2006 at 03:57:01PM -0700, Jonathan Lang wrote: Tim Bunce wrote: Damian Conway wrote: Dave Whipp wrote: I'm not a great fan of this concept of reservation when there is no mechanism for its enforcement (and this is perl...). What makes you assume there will be no mechanism for enforcement? The standard Pod parser (of which I have a 95% complete Perl 5 implementation) will complain bitterly--as in cyanide--when unknown pure-upper or pure-lower block names are used. That's going to cause pain when people using older parsers try to read docs written for newer ones. If I understand you correctly, the pain to which you're referring would come from the possibility of a name that's reserved by the newer version of Pod, but not by the older version. Yes. Wouldn't the simplest solution be to let a Pod document announce its own version, much like Perl can? How would that actually help? The old parser still wouldn't know what new keywords have been added or how to parse them. Tim.
Re: Synposis 26 - Documentation [alpha draft]
Jonathan Lang wrote: The only thing that I'd like to see changed would be to allow a more flexible syntax for formatting codes - in particular, I'd rather use something analogous to the 'embedded comments' described in S02, replacing the leading # with an appropriate capital letter (as defined by Unicode) and insisting on a word break just prior to it. It was a deliberate decision to restrict the delimiters to angles. Unlike embedded comments, formatting codes are predominantly embedded in text, not code, so it's important to keep them easy-to-locate (i.e. with a consistent delimiter) and not to allow too many syntaxes (which increases the chance of unintended codes in normal text). A leading word break is not really practical either, since documenters will need to use codes in the middle of words: PractIise (and then practIice) saying GarEccedilon! I'd also prefer a more Wiki-like dialect at some point (e.g., '__underlined text__', '_italicized text_' and '*bold*' instead of 'Uunderlined text', 'Iitalicized text' and 'Bbold'); but that can wait. That's Kwid. Which Ingy has proposed as a standard Perldoc dialect. You'll be able to flip into kwid mode (for Perldoc parsers that support it) using: =begin kwid =end kwid Damian
Re: Synposis 26 - Documentation [alpha draft]
Dave Whipp wrote: I'm not a great fan of this concept of reservation when there is no mechanism for its enforcement (and this is perl...). What makes you assume there will be no mechanism for enforcement? The standard Pod parser (of which I have a 95% complete Perl 5 implementation) will complain bitterly--as in cyanide--when unknown pure-upper or pure-lower block names are used. The whole point of reserving these namespaces is not to prevent users from misusing them, but to ensure that when we eventually get around to using a particular block name, and those same users start screaming about it, we can mournfully point to the passage in the original spec and silently shake our heads. ;-) Damian
Re: Synposis 26 - Documentation [alpha draft]
I liked it. Just one nit, near the end: You can also preconfigure Lformatting codes|#Formatting codes, by naming them with a pair of angles as a suffix. For example: =comment Always allow E codes in any (implicit or explicit) V code... =config V :allowE =comment All code to be italiciized... ^^ =config C :formattedI Note that, even though the code is named using single-angles, the preconfiguration applies regardless of the actual delimiters used on subsequent instances of the code. s/italiciized/italicized/ in the marked place. -- Customer Waiter, waiter! There's a fly in my soup! Waiter That's not a bug, it's a feature. http://surreal.istic.org/ It sounded right in my head.
Re: Synposis 26 - Documentation [alpha draft]
Damian Conway wrote: Delimited blocks are bounded by C=begin and C=end markers... ...Typenames that are entirely lowercase (for example: C=begin head1) or entirely uppercase (for example: C=begin SYNOPSIS) are reserved. I'm not a great fan of this concept of reservation when there is no mechanism for its enforcement (and this is perl...). Typical programmers ignore it, just as they ignore similar reservations of the type lower-case subroutine names are reserved. If use strict will flag an error for their use, then perhaps is reserved would become must be predeclared (imported via =use). Then any module will be able to add its own typenames, without needing some distinguishing this is a core module trait to enable the typename. Reservation then simply becomes a note to module authors, not part of the language specification.
