Time for the second user portrait and story. There are so many of these I want to write, and have uses for, but I'll try to add them one at a time. This helps support the development process, and keeps everything focused on users and actual needs.
As usual, it's followed by an update on the code.
User: Fionn
Fionn is a 45 year old content writer. He lives in a rural community and does remote freelance work for various publications and content providers. He writes about politics, and whatever the content agency requires.
His main product is Word, where he uses a simplified stylesheet. He uses styles to do standard markings, but also has special styles for notes to himself. These are notes that he has to remove manually before sending it to the editor. He'd also be happy with a solution that isn't so bulky. As he works only with the text he doesn't need any formatting features; he leaves that to the editors.
I'd like to help Fionn with his work. I think an improved markdown would fit his needs. Well, not in the short-term. It's unlikely he'd accept a text-based solution. He'd prefer to have a graphic editor as that's what he's used to. Perhaps I could upsell him. But instead I'll focus on the underlying technology that a web front-end might use.
The key feature here is the private markings. These sound like source code comments. We can see them in places like collaborative editing tools. I think both inline and paragraph markings would make sense. I'm going to focus on the paragraphs markings first. Note: in terms of user story analysis, this is a potential conflict. It would make sense to determine what Fionn really needs.
My personal needs for commenting is to include notes in the docs about unsupported features they need. At the moment this is recording the date of publication of each of these logs.
Comments
Comments sound like a non-functional annotation. They are information for the source doucment but won't appear in the output. They will however appear in editing tools. This is relevant since it means they have to exist inside the doc-tree and survive a round-trip. This makes them unlike source code comments which can be stripped by the parser as fast as possible.
I've added full-block comments leading with // and single-line comments leading with /. Single-lines terminate at the end of the line. Full-block are parsed like a normal block. Both are attached to the next paragraph as a comment annotation. This document has comments in it, but being comments, they don't make it into this update. :)
Refactoring
I've simplified the doc-tree structure. No longer will there be a class per semantic type, but just one Block class with a class type. To keep things simpler going forward I think the doc-tree will be based on structure, rather than semantic form. This will result in a lot fewer Python types, thus making it easier to process.
It's not without some drawbacks though. Without a high-level encoded type some processors and the emitters have to be a bit more careful. Falling back to a basic paragraph type is also easy -- but whether this is desired or not isn't certain.
At the moment it may seem like the doc-tree mimics the parse-tree, making it hard to understand why we need this distinction. For the features supported so far there is no real need for the separation. As I add some more features it'll become more apparent why.
This is a development log entry for the MDL Document Processor Project.
Top comments (2)
I’m wondering, are you starting with standard markdown and extending it or starting from scratch?
I'm starting with a markdown inspired, but not markdown syntax.
I'm following the user stories to decide which features come. They relate to high-level features I need (in view of those users) in such a language.
Markdown has many things that will simply never be required -- such as the awful table support. It'd be a waste of time to implement those now.
Eventually a user story will be produced saying something like, "Mike has an existing set of markdown documents". And then I'll have to support it.