A major change to Leo's markdown importer
26 views
Skip to first unread message
Edward K. Ream
Dec 2, 2016, 9:23:03 AM12/2/16
to leo-e...@googlegroups.com
As of rev e90fc6b, Leo's markdown importer converts all sections to '#' sections. The technical justification appears at the bottom of the page for #342. The rest of this post explains the change from a user's point of view.
tl;dr: Converting all sections to '#' markup is Leonine, simplest and best. Only existing .md files that Leo didn't write could be changed. If such changes don't work for you, just insert @ignore yourself when git or diff reports differences.
Justification
Imo, this change is fully justified:
1. It is more Leonine.
When creating and changing .md files from within Leo, @auto-md works much more smoothly. Indeed, as I have just verified, converting an @nosent x.md file to @auto-md x.md "just works".
There is absolutely no reason to use underlined sections when using Leo. The headlines proclaim the section structure far better than flat text of any kind, whether ### section name or underlined section names.
2. Perfect import checks should not wag the dog.
The markdown importer is one of the simplest of all. The possibility of dropping data seems remote. Requiring a typical perfect import check to pass would preclude regularizing section markup. It's just that simple.
Furthermore, the existing unit tests for the markup importer do check imported section structure, albeit imperfectly. That should suffice for now. In the unlikely event that real problems are reported, these after-the-fact unit tests can be improved.
Summary
Importing markdown files containing underlined sections could only pass typical perfect import checks if existing underlining were somehow retained. That's a bad idea. Instead, Leo's markdown importer now implicitly converts all sections to '#' markup. In essence, the markup disappears from the outline, to be automagically reinserted when Leo writes the outline.
This new scheme can change existing .md files, but only files that Leo didn't write. If that is inconvenient for you, just add @ignore yourself.
Edward
tl;dr: Converting all sections to '#' markup is Leonine, simplest and best. Only existing .md files that Leo didn't write could be changed. If such changes don't work for you, just insert @ignore yourself when git or diff reports differences.
Justification
Imo, this change is fully justified:
1. It is more Leonine.
When creating and changing .md files from within Leo, @auto-md works much more smoothly. Indeed, as I have just verified, converting an @nosent x.md file to @auto-md x.md "just works".
There is absolutely no reason to use underlined sections when using Leo. The headlines proclaim the section structure far better than flat text of any kind, whether ### section name or underlined section names.
2. Perfect import checks should not wag the dog.
The markdown importer is one of the simplest of all. The possibility of dropping data seems remote. Requiring a typical perfect import check to pass would preclude regularizing section markup. It's just that simple.
Furthermore, the existing unit tests for the markup importer do check imported section structure, albeit imperfectly. That should suffice for now. In the unlikely event that real problems are reported, these after-the-fact unit tests can be improved.
Summary
Importing markdown files containing underlined sections could only pass typical perfect import checks if existing underlining were somehow retained. That's a bad idea. Instead, Leo's markdown importer now implicitly converts all sections to '#' markup. In essence, the markup disappears from the outline, to be automagically reinserted when Leo writes the outline.
This new scheme can change existing .md files, but only files that Leo didn't write. If that is inconvenient for you, just add @ignore yourself.
Edward
Edward K. Ream
Dec 2, 2016, 9:36:26 AM12/2/16
to leo-editor
On Friday, December 2, 2016 at 8:23:03 AM UTC-6, Edward K. Ream wrote:
As of rev e90fc6b, Leo's markdown importer converts all sections to '#' sections.
Eating my own dog food has instantly revealed some minor problems. I'll fix them immediately.
EKR
Edward K. Ream
Dec 2, 2016, 10:55:53 AM12/2/16
to leo-editor
Done at 58369de. The new code is much simplified, and follows the general pattern of the super-simple rst importer.
I am now using @auto-md importers.md in leoDocs.leo without any apparent problems.
Please do report any new problem immediately.
Edward
Reply all
Reply to author
Forward
0 new messages