This is an Engineering Notebook post, with many technical details. Otho,
many people are affected by the "huh?" and they may like a full explanation.
The importers for .ipynb, .md, .org, .otl and .rst files put this warning
in the root @auto node:
Warning: this node is ignored when writing this file.
Huh? Why ignore the root @auto node? This confuses me every time I see it.
This post will discuss why these warnings are necessary.
*tl;dr:* Read the summary.
*Why ignore root @auto nodes?*
Let's discuss each language separately:
*.ipynb files.* Such files are .json files representing a series of
cells. The only natural representation of the cells is as a list of
children of the root @auto node. Therefore, * it doesn't make sense* to
write the root node.
*Important*: Even though the .ipynb writer ignores the @auto node itself,
the @auto node contains useful directives, namely the @language and
@tabwidth directives.
*.org and .otl files.* The file formats divide a text file into a series of
nodes, delimited by lines similar to Leo's sentinel lines. But neither org
mode nor vimoutline mode files define any comment conventions. All lines
are significant. Therefore, it is *impossible* to support either @others
or section references in the root @auto node.
Suppose the writer wrote the contents of the @auto node. There are two big
problems:
1. [Serious] The writer would have to ignore all Leo directives. Remember,
there is no way to represent Leo directives in .org or .otl files. This
would be confusing. The user might expect those sentinels to carry over
when the file is next imported, but they won't be.
2. [Fatal] It would be too easy to break the file format. In both formats,
files must start with a sentinel line indicating the start of a node.
These sentinels are org mode or vimoutline mode sentinel line, *not* a Leo
sentinel line! *Writing root @auto node will likely break the resulting
file*.
*.md and .rst files.* For such files, it would, theoretically, be safe to
allow the user to put real data in the root @auto node. Unlike .otl and
.org files, markdown and reStructuredText (rST) sections can be preceded by
plain text. However, nothing can be gained by doing so.
The markdown and rST importers already allow plain text to precede the
first section. Furthermore, *it doesn't make sense* to allow @others or
section references in the root @auto node. In fact, the *only* reasonable
place to write data in the root @auto node would be at the start of the
file, that is, at the start of the first section of the file.
In short, allowing the user to put text in the @auto node for rST and
markdown files promises more than can be delivered.
*Summary*
For all these file formats, *it doesn't make sense* to write the @auto
node. At best, doing so would promises more than can be delivered. At
worst, writing the @auto node would break the file format.
These warnings disrupt the *illusion* of simplicity. It would be good to
maintain that illusion, but that's not going to happen. That best that can
be done is to improve the "huh?" messages, explaining why the @auto node
can't be written and suggesting that the user change the first child node
instead.
The root @auto nodes still are useful: they provide a place for Leo
directives that could not be placed anywhere else. The root @auto nodes
provide a necessary parent for all imported children.
Your comments, please. I plan to update the warning messages later today.
The idea is to convert warnings into explanations.
Edward
P. S. Some implementation details, as background:
When *writing* *most *imported @auto nodes, Leo calls at.writeOneAtAutoNode
in leoAtFile.py. This allows the imported files to support @others and
section references. When *checking* just-imported files, most importers
again call at.writeOneAtAutoNode.
Leo uses a *custom writer* for .ipynb, .md, .org, .otl and .rst files.
Importers for .ipynb, .md and .rst files override either i.run or i.check.
These importers do *not* perform perfect import checks. Importers for .org
and .otl files *do* perform perfect import checks.
EKR
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to leo-editor+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.
