PRMarkdownWriter >>visitAnnotatedParagraph: says "Pier seems to lack
consistency here ...".
Indeed, for #visitAnnotatedParagraph: we currently have:
* PRPillarWriter outputs all annotations unchanged
* PRMarkdownWriter
* prepends the the annotationLabel to the annotationText
* has special handling for @@todo by calling #visitCommentedLine:
* indicates it does some kind of nesting in a custom way; but I
can't work out the semantics; and it interrupts nested list numbering
similar to what I reported for comments.
* PRVisitor
* throws away the annotationLabel by just calling #visitParagraph
* knows nothing about @@todo
* knows nothing about nesting
* PRHTMLWriter has no definition inheriting from PRVisitor
* PRLaTeXWriter has no definition inheriting from PRVisitor
* PRTextWriter has no definition inheriting from PRVisitor
To bring some consistency I propose to...
1. Prepend annotationLabel for all the xxWriters
2. Change PRMarkdownWriter to use the code I implemented for nested
comments. Have all xxWriters use this also.
3. Drop the @@todo from PRMarkdownWriter, since if you want ToDos to be
hidden like a comment, you should just use a comment, e.g." %todo ..."
. However this change would alter the semantics of existing users of
Pier. So what is the process for such changes? Announce here and wait
some period? For consideration, there are currently no tests for
annotated paragraphs, so this could be considered outside the existing
API ;) - and so I'll add tests, which will be simpler without @@todo.
cheers -ben
