Second draft of rst3 tutorial now on the web
Edward K. Ream
has a proper introduction. Comments about the overview and tutorial
are welcome now.
The "Advanced features" section is not ready for prime time. I'll be
working on it today.
Edward
Ville M. Vainio
> The "Advanced features" section is not ready for prime time. I'll be
> working on it today.
I guess @auto-rst should not be an "advanced feature", as it's
conceptually (and in practice) simpler than rst3.
--
Ville M. Vainio @@ Forum Nokia
Edward K. Ream
> On Tue, Aug 10, 2010 at 5:03 PM, Edward K. Ream <edre...@gmail.com> wrote:
>
>> The "Advanced features" section is not ready for prime time. I'll be
>> working on it today.
>
> I guess @auto-rst should not be an "advanced feature", as it's
> conceptually (and in practice) simpler than rst3.
Thanks for this reminder. Actually, it doesn't really belong in
Chapter 14 at all. It probably belongs in Chapter 4.
Edward
Edward K. Ream
> > The "Advanced features" section is not ready for prime time. I'll be
> > working on it today.
http://webpages.charter.net/edreamleo/rstplugin3.html#intermediate-topics
now contain the first draft of the rest of Chapter 14, now called
"Creating Documents with Leo".
There are two main parts following the tutorial, an "intermediate
topics" section with items of general interest, and the "advanced
topics" section that covers the horrors of code mode and per-mode
settings. As the introduction to the advanced topics makes clear, all
these complexities arise from the desire to create documents
automatically from computer source code.
One has hopes, therefore, that the average user of the rst3 command
will ignore the advanced section completely. That's the best we can
do, imo. Unlike @root, code mode is something useful, at least for
some. Having said that, it wouldn't kill Leo to get rid of everything
in the advanced section. I don't think that is required: confining
the horrors to the advanced section should suffice.
Edward
P.S. I did kill the documentation for the "feature" that allow users
to redefine the *names* of @rst commands. I have no idea why I
thought that was important.
P.P.S. While writing the docs, I realized that @rst headlines
(without filename) *supposedly* revert to rst mode. Looking at the
code, I have grave doubts about that :-) I plan to change this to
@rst-rst to eliminate confusion. Or it could just go away: it's
possible to revert to rst mode using option doc parts.
EKR
Edward K. Ream
> As the introduction to the advanced topics makes clear, all
> these complexities arise from the desire to create documents
> automatically from computer source code.
When I awoke this morning, I started wondering whether "overloading"
markup in nodes (headlines, doc parts) might eliminate the need for
all the code-mode options, which would in turn eliminate the need for
code mode.
I'll be playing around with these ideas here. Now is the time to do
so, while the "horrors" are fresh in my mind.
The basic ideas:
All modes would treat docs "specially, but uniformly". This would not
be a big deal for rst mode: one could disable this using \@. In other
words, only '@', not '\@' would start a doc part as far as the rst3
command is concerned.
So the question is, how should the rst3 command treat doc parts in *all* modes?
This is not a big deal for rst mode, because **users don't typically
use doc parts in rst mode**, and the \@ convention (or more likely,
literal blocks) allows anything, including what looks like a doc part,
to be represented in rst mode.
Thus, the question becomes, what's the most useful way to treat doc
parts in code mode? Whatever we decide will become the *universal*
way of treating doc parts, even in rst mode. That is, we could
eliminate modal operation entirely!
Now we have some real choices. Here are the code-mode options.
number_code_lines
show_leo_directives
show_markup_doc_parts
show_options_doc_parts
show_doc_parts_as_paragraphs
show_options_nodes
Let's consider the usual case of formatting an outline containing
source code. Typically, the user
will put the desired defaults at or near the root of the tree using @
@rst-options. This option doc part
will be invisible to the rst3 command if show_options_doc_parts is
False. It's unlikely that *code* documentation
is ever going to want to show an @ @rst-options node, and in that
event, the docs could "simulate" the @ @rst-options using an @
@rst-markup node!
The only complication is the interaction between
show_doc_parts_as_paragraphs, show_markup_doc_parts and
show_options_doc parts, but I think such interactions will be rare
enough to be handled by embedded @ @rst-options and/or @ @rst-markup.
Let's step back a moment and ask some questions.
- Does the show_doc_parts_as_paragraphs option handle most common
situations when formatting code?
Yes, I think it does.
- Are @ @rst-options and @ @rst-markup to handle almost any
contingency when formatting code?
Yes, I think so.
4. Will eliminating code mode inconvenience rst mode (especially
newbies) in any significant way?
No, I don't think so.
1. Is there, in fact, *any* need for code mode?
I think not. We can eliminate code mode **provided** that
1. The tutorial tells newbies that the rst3 command treats doc parts
specially and
2. The rst3 command does, in fact, treat doc parts uniformly in all situations.
In short, I think a major simplification may be possible. But before
reaching a firm conclusion, I'll look at the code for the rst3 command
to see if there might be code-level gotchas. I suspect not. Instead,
I expect to be able to clean up the code significantly. We shall
see...
Edward
P.S. I remember reading that the original Unix developers sometimes
fixed bugs because they simply could not bear to document them :-)
Revising the rst3 docs may have been a similar situation...
P.P.S. I haven't discussed headlines here. This might be a
mini-gotcha. I have no idea whether code mode treats headlines in a
special way. If it does, I could always create another option that
would, in effect, distinguish
between the two ways of handling headlines without actually
re-creating code mode itself.
EKR
EKR
taa, Leo Newbie
OF COURSE had a power glitch and lost 'em all! :( Too tired to
recreate them tonight.
> There are two main parts following the tutorial, an "intermediate
> topics" section with items of general interest, and the "advanced
> topics" section that covers the horrors of code mode and per-mode
> settings.
a lot. I may freak when I see how long the chapter is, but when I
realize I don't need to worry about the advanced topics, it instantly
becomes less overwhelming. :D
taa, Leo Newbie
> has a proper introduction. Comments about the overview and tutorial
> are welcome now.
Here's a link to see the highlights and sticky notes: http://diigo.com/0c9u2
This is an experiment as I've been researching Diigo-like services for
about a week, and would like to know if this would be an acceptable
method when there are lots of things to be commented on for Leo's web
pages. Otherwise I would do email when there are only a few comments.
When you go to the link, you'll see pink highlighted text, with a
small icon in the top left of each text "piece" with a number. Hover
over it to cause the sticky note to be displayed. The number
represents the number of comments entered on the sticky note.
Usually when I'm highlighting edits to be made (like in Acrobat), I
only highlight the specific word or punctuation that needs attention.
With Diigo, there are two problems:
a) there seems to be a minimal number of characters that need to be
highlighted before you get an option to add a sticky note, and
b) Diigo appears to "remember" the location of highlights/stickies
based on where the text first occurs on the page. If you highlight
text halfway into the document that also appears at the beginning of
the document, reloading the web page causes your highlight to "move"
without warning to the beginning of the document. This took a while
for me to realize, because I'd keep redoing highlights, not knowing I
was spinning my wheels. (I don't know what will happen to these
annotations if Chapter 14 is changed and reuploaded. Probably it will
still "find" the highlighted text that hasn't changed and be able to
show the sticky notes.)
The solution to both issues is to highlight more text than you want,
and make sure it's enough text to identify its location uniquely on
the web page. I noted in the sticky note where extra text highlighting
was done, eventually saying I did it due to a Diigo bug.
You do NOT need to sign up for Diigo to see the edits, but there are
two benefits I can see for collaborating on web pages. If you had an
account (and you can use your Google account, like I did), you could:
1) Add comments to the comments I've made. Without an account, when a
sticky note is displayed, it acts like you could type in a comment and
click on Post. But when you click on Post the comment is not saved
anywhere, and there's no message that it was sent to /dev/null.
2) Navigate easier through the list of annotations, if you also
install the Diigo toolbar. There's a "Comment" button that when
clicked opens up a side bar listing all annotations. The biggest
feature I wish Diigo had was an easy way to go to the previous/next
annotation to be sure I see them all.
3) Create the first sticky note for highlighted text that Diigo has
trouble dealing with: Text highlighted at the very beginning of the
line causes the icon to appear at the very end of the line above it.
The problem is, you need to hover over the highlighted text to cause
the icon to appear that allows adding the sticky note. But you can't
move the mouse fast enough :) from the highlighted text to the icon at
the end of the line above it. The solution is to sign in to your Diigo
account, go to My Library, find your highlighted text and choose the
"Add Sticky Note" link.
Phew, been working on this and the Chapter 14 edits for hours. Time to
take a break.
Edward K. Ream
>> For the first time the rst3 chapter http://webpages.charter.net/edreamleo/rstplugin3.html
>> has a proper introduction. Comments about the overview and tutorial
>> are welcome now.
>
> I've recreated my feedback notes using the online service Diigo.
> Here's a link to see the highlights and sticky notes: http://diigo.com/0c9u2
Thanks for these. I'll make the corrections asap.
Edward