ENB: Huh? Warnings in @auto root nodes

[Edward K. Ream]

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