Ben Coman wrote:
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
Now I discovered existing tests...
PRAnnotatedParagraphTest>>testParseBasic
| wiki text tree |
wiki := '@@foo bar zork'.
text := 'bar zork'.
which with this proposal would become...
text := 'Foo: bar zork'.
PRAnnotatedParagraphTest>>testParseOnlyAnnotation
| wiki text tree |
wiki := '@@foo'.
text := ''.
would become
text := 'Foo:'.
etc! This is since existing PRTextWriter throws the annotation label away.
So on the side of:
* "include annotation label" we have PRMarkdownWriter & PRLaTeXWriter,
* "exclude annotation label" we have PRHTMLWriter & PRTextWriter.
To resolve this discrepancy, I lean towards the former, so you can
differentiate between annotation types in the produced document. So I
will update the PRAnnotatedParagraphTest methods accordingly.
btw, with PRHTMLWriter I am using...
canvas tag
name: 'p';
parameterAt: 'class' put: anAnnotatedParagraph annotation; ...
so that each annotation type can be separately styled by CSS.
cheers -ben
[1]
http://forum.world.st/Pharo-users-smallwiki-Pillar-annotations-for-Latex-tt4760229.html
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
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki
