On Wed, 2005-03-16 at 13:42 -0800, Brian Ingerson wrote: First off, thanks for your kind responses. I'm sure I just got confused by some web page I was looking at, and overwrote part of my stack that I'd just populated from the Kwid doc. And thanks also for pointing me to the Kwid docs where they live now.
> In short you don't need to worry about I[[ $foo[3] ]]. Since the ending > marker is '/}', you only ever need to worry about escaping anything but > '/}' itself. I might as well show how that would be done: We're suffering a major disconnect over the nature of bracketting. I see no reason to I[[ $foo[3] ]] at all. That would simply be I[$foo[3]] ... we are using a real parser here, no? I can't imagine basing this on some pile of regexps, and we all have "matched the balanced brackets" tools at our disposal, regardless of what parser / parser-generator we're using these days. Here's a simple Parse::RecDescent grammar for my proposal, so that we can talk about it in more reasonable terms. Please note that I'm TERRIBLE with P::RD, so I'm sure someone can figure out why I keep ending up with the string "text_chunk" in my resulting syntax tree ;-) See attached program and sample input. Just run parseajskwid.pl on ajskwid.kwid. > For some reason Pod does not allow L<text|url> but there seems to be no > obvious reason. (This is the the only major thing where Kwid strays from > Pod's info model). That's not POD's info model, that's POD's implementation limitation. > I am not certain what use case `L[...]` could get you that isn't already > covered by `[...]`. I'm very happy with the modern Wiki convention (keep in mind, when we talk about Wiki, we're talking about something that's either nearly as old as or older than the Web, depending on what you count as it's birth) of using [...] as a sort of magical indexer. Like I said elsewhere, you might have: [Kwid] in your document. This is a hint that you expect there to be a thing named "Kwid" somewhere and you wish that somewhere to be applied thusly: L[Kwid|somewhere] in your document. Where L[Kwid] would simply fail because it is as strict as POD, and it won't find L[Kwid|perlkwid]. Other examples of this DWIMery: [http://www.perl.org/] => L[http://www.perl.org/|http://www.perl.org] [;-)] => =for html <img src="winksmily.png" alt=";-)" /> =for !html ;-) > > How, then do you differentiate: > > > > * Bullet list. > > 1. Numbered list. > > Other > > Term/definition lists [...] > In Kwid, therefore, this: > > * Bullet list. > + Numbered list. > - Other > Term/definition lists That was the answer I was looking for, thanks. I'm not thrilled with it (again, too many special characters that people might have thought they could get away with using in their documentation), but it's not too bad at all. > > Sorry, no access to IRC at work. If the specification of core pieces of > > P6 are being done off-list, why is there a list? > > Honestly this project was started as an /experiment/ and was not > intended to distract p6l. Kwid requires no extra input from the language > side as long as: > > =kwid > ... > =cut Well, look over AJS Kwid, and see what you think. The bullet syntax you give could work fine as a replacement for what I demonstrate, but I think everything else is pretty much 1:1. Now it's just a matter of: do you make it Wikiish or PODish?
= AJS Kwid
== Introduction
Hello, and welcome to B[AJS Kwid], an experimental form of a proposed
syntax and grammar for Perl 6 documentation.
== Why Kwid?
Kwid was originally proposed for several reasons, and I'll let the
authors of that proposal speak for themselves. However, it has been
selected as the basis of AJS Kwid for the following reasons:
* It is much terser, while maintaining readability.
* It maps closely to Wiki syntax, which is well known.
* Some features (e.g. the C[[...]] linking) are more flexible.
== Why AJS Kwid?
AJS Kwid is an attempt to introduce a bit more I[PODishness] to
the Kwid syntax. Not much of Kwid is changed in any real way, only
the extent to which it closely resembles POD.
=== Was Kwid Broken?
Not at all. Kwid was fine as is, when taken on its own. Only in terms
of the human elements of POD compatibility was it problematic
(that is, internally it was construct-for-construct, a complete
POD replacement, but did not "feel" like POD, and thus the
transition from Perl 5 would be even more jarring than Perl 6
is likely to make it).
== AJS Kwid Elements
The elements of AJS Kwid are fairly simple:
=begin list
* Newline (or CR/NL) separated lines
* Empty lines are treated as paragraph breaks.
* Each line can start with C[=], C[*], whitespace, or any text-component.
**= C[=]
Introduces a command.
***= C[=begin word]
Begins a block of type "word", which is ended with an C[=end word]
line, later in the document. Such typed blocks must match up, so
you have to end a C[=begin foo] with a C[=end foo].
***= C[=[=...]] string
Is a heading named "string". The "heading level" is indicated by the
number of C[=] signs.
**= *
Introduces a list item. The number of C[*]s indicates the nesting-level.
There are three supported kinds of list:
***= Bullet
A bullet list has no special syntax other than the leading
C[*]s.
***= Numbered
A numbered list must have leading C[*]s to indicate the nesting
level, followed by a single C[1] to indicate numbering is required.
***= Terms
A term list is like an entry in a dictionary, or this very list
that you're reading, where terms are followed by a block of text
that relates to the term.
Term lists are introduced by the leading C[*]s to indicate the
nesting level, followed by a single C[=], followed by white-space,
followed by the term. A term can be any text, as long as it
is on the same line as the C[*=].
**= Text components
A text component is a collection of text and inline-directives on a
single line. An inline directive is one of:
***= C[x[...]] or C[x{...}]
The enclosing C[[]]s or C[{}]s are interchangable (the
only difference is that you can have unbalanced C[{}]s inside
of C[[]]s and you can have unbalanced C[[]]s inside of
C[{}]s. C[x] can be any alpha chracter, but the defined types are:
****= B
The enclosed text is treated as normal text, but the "bold"
attribute is added.
****= C
The enclosed text is treated as normal text, but the "literal"
attribute is added. This might be rendered in any number of ways,
but it should be assumed that as long as there are no unbalanced
C[[]]s, the text will be rendered without interpreting any of the
contents as AJS Kwid code.
****= E
The enclosed text is treated as the name of a character to
insert. Valid names include the HTML character names and escape
codes (sans the leading C[&] and trailing C[;]), as well as the
full Unicode character names.
****= I
The enclosed text is treated as normal text, but the "italic"
attribute is added.
****= L
The enclosed text is interpreted as a link name. It may be of the form
C[text|link] or just C[link]. A link is of the form
C[[text|][scheme:]label[/extra]].
the optional C[text|] is any descriptive text that should be associated with
the link, followed by a C[|] which is just a separator.
The format of the label and extra are dependent on
the scheme, and the default scheme is C[kwid]. The format of the label for
C[kwid] is just the name of a Kwid document, which can be found via
your Kwid interpreter's search path. The special document C[.] refers
to the current document. The format of the optional C[extra] is free-form,
and will refer to a heading name, term list item name or C[X[...]] tag
in that document.
Other available schemes include the valid [URI] schemes (in which case the
whole link is interpreted as a URI).
New schemes may be added at any time.
****= X
The enclosed text is the name of an "anchor". An anchor can be used
for many purposes, and the specific meaning is dependent on the
format or rendering engine you are using for AJS Kwid.
However, the two primary purposes would be to allow L[L] links
to link to the area of the document where the C[X[...]] occured,
and to build a document index or table of contents.
=end list
parseajskwid.pl
Description: Perl program
