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
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-tt4...
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
On Sun, Jun 1, 2014 at 11:37 AM, Ben Coman <btc@openinworld.com> wrote:
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
I agree that we can do better than the current situation but I disagree with your solution. Annotated paragraphs are a way to have different kinds of paragraphs. Printing the kind is not the right way to do it. I like your solution of using the "class" parameter in HTML. The same should apply in LaTeX. For text, I think the annotation should have no impact on the output (just as it is now). For Markdown, we should probably have the same solution as for HTML. What do you think? -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
participants (2)
-
Ben Coman -
Damien Cassou