On Aug 9, 9:52 am, "Edward K. Ream" <[email protected]> wrote:
> Perhaps modes are the real problem. In effect, iirc, modes are a
> shorthand for a list of options. Might it make sense to require
> options to be listed independently? Maybe, but somehow I doubt it.
>
> Ok. Now that I have the issues more firmly in mind it is time to go
> back and study what presently exists...
I see the problem: there is a combinatorial explosion of possibilities
in the following four options:
code_mode (default: False)
In code mode, the rst3 command automatically creates rST markup to
display the body text as an rst code-block. In rst mode the rst3
simply copies the body text of the node to the output. That is, the
rst3 command assumes that body text is already valid rST markup.
doc_only_mode (default: False)
In doc_only mode, the rst3 command outputs only regular doc parts and
@ @rst-markup doc parts. Headlines create sections in doc_only mode
only if a) the node contains a doc part or b) the show_organizer_nodes
option is in effect. As always can use @ @rst-options for per-node
control of the process, especially node-by-node control of the
show_organizer_nodes option.
show_doc_parts_as_paragraphs (default: False)
True: Move doc parts outside of the code-block directive in code mode.
This option has no effect in rst mode. Cool: Any rST markup in doc
parts included as the result of this option will be rendered properly.
show_doc_parts_in_rst_mode (default: True)
This option is most useful for rst documents which are not
computer code. It allows you to use doc parts to make comments on the
draft document which are either excluded from the output or formatted
in a way that highlights their nature as comments rather than content.
[example deleted] True: The entire doc part from the opening �...@’ to
the closing �...@c and everything in between are treated as normal rST
markup. False: doc parts are removed from the output in rst mode
I can see how this mess might have happened. The scenario is:
1. At first, the "plugin" (rst3 command) treated everything as rST
markup. This is rst mode (code_mode = False)
2. The fun began when we wanted to format nodes containing source doe
(code_mode = True).
Alas, once we think in terms of modes we are screwed. The options
instantly become unintelligible and they start to interact in almost-
impossible-to-predict ways. Actually, rst mode *disables* most
options, so the combinatorial explosion isn't as bad as we might
think,
but it's not easy to see that from the present docs.
I believe the solution may be to treat code and docs completely
independently. Something like this, with indicated defaults:
plain_doc_parts [ignore,copy,in_code_block] = copy
option_doc_parts [ignore,copy,in_code_block] = copy
code_parts [ignore,copy,in_code_block] = in_code_block
headline [ignore,create_section] = create_section
There are 3 x 3 x 3 x 2 = 54 possibilities here, yet unlike the
previous scheme all the possibilities are easy to understand.
This seems to cover all *reasonable* possibilities. We don't go the
xslt route, where any transformation of the sources is possible :-) It
should be good enough to stick with the order of code and doc parts in
a node.
But wait, there are other rst3 options:
show_headlines (default: True)
True: automatically generate rST sections from headlines. Applies
to both code mode and rst mode. The level of the node in the outline
determines the level of the section underling in the rST markup.
Higher-level headlines in the outline correspond to higher-level
section headings; lower-level headlines in the outline correspond to
lower-level section headings.
show_leo_directives (default: True)
True: include Leo directives in code mode. This option has no
effect in rst mode.
show_markup_doc_parts (default: False)
True: include markup doc parts in code mode. This option has no
effect in rst mode.
show_options_doc_parts (default: False)
True: include options doc parts in code mode. This option has no
effect in rst mode.
show_options_nodes (default: False)
True: show @rst-options nodes.
show_organizer_nodes (default: True)
True: generate rST sections for nodes that do not contain body
text. This option has no effect unless the rST section would otherwise
be written.
show_sections (default: True)
True: generate rST sections corresponding to headlines. False:
don’t generate sections. Instead, generate lines of the form:
**headline**.
The "refactoring" of these options would be something like this:
plain_doc_parts [ignore,copy,in_code_block] = copy
option_doc_parts [ignore,copy,in_code_block] = copy
markup_doc_parts[ignore,copy,in_code] = copy
code_parts [ignore,copy,in_code_block] = in_code_block
headline [ignore,copy,create_section,] = create_section
organizer_nodes [ignore,copy,create_section] = create_section (?)
options_nodes[ignore,copy,in_code_block] = ignore
leo_directives [ignore,copy,in_code_block] = ignore
There are 3**8 possibilities here!
The only question is, are their even more possibilities to consider?
Yes, there is. One @rst users has requested expansion of section
references (!) I'm not sure that's a great idea, or even if it really
makes sense, but supposing it does we could add it easily enough in
the new scheme:
section_references
[ignore,copy,in_code_block,expand_in_code_block,expand_in_rst]
This merely quintuples the total possibilities :-)
Summary
At present, the "great divide" is between code mode and rst mode
(code_mode = False). rST mode agglomerates options, but this is more
of nuisance than a convenience.
It would seem more reasonable and much more flexible to treat all
syntactic parts of a Leo node separately, without regard to mode. The
list of syntactic parts of a node would surely include headlines, code
parts, doc parts, option doc parts and markup doc parts. The list
would probably include Leo directives, and might even include section
references.
The new organization of options seems like the most general scheme
possible because it handles all possibilities related to what Leo has
a "right" to know about. The new organization, while not exactly
simple, looks like the simplest that could possibly work.
I think this kind of scheme is likely to suffice for almost everyone.
If not, users could write scripts, I suspect very few would actually
do so...
All comments welcome. I don't plan any work on this any time soon,
except maybe for revising the docs to clarify and emphasize the "great
divide" between code mode and rst mode.
Edward
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/leo-editor?hl=en.
