PIllar >> #visitAnnotatedParagraph:

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:
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

On Sun, Jun 1, 2014 at 11:37 AM, Ben Coman <[hidden email]> 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

Damien Cassou wrote:
I've uploaded the updates to make annotations more consistent, and added
the \dothis LaTeX command being used in the PharoLaserGame tutorial.

source
         annotation test
         # item 1
         @@note anno1
         @@dothis anno2
         ## item 11
         @@note anno3
         ## item 12
         @@dothis anno4
         ## item 13

--to=pillar
         annotation test
         # item 1
         @@note anno1
         @@dothis anno2
         #
         ## item 11
         @@note anno3
         #
         ## item 12
         @@dothis anno4
         #
         ## item 13
Now this output is not the same and the source. Should I try to fix this
the same as I did for comments.

--to=html
     <div class="container">
        <p>annotation test</p>
        <ol><li> item 1 </li></ol>
        <p class="note">anno1</p>
        <p class="dothis">anno2</p>
        <ol><li>  <ol><li> item 11 </li></ol>  </li></ol>
        <p class="note">anno3</p>
        <ol><li>  <ol><li> item 12 </li></ol>  </li></ol>
        <p class="dothis">anno4</p>
        <ol><li>  <ol><li> item 13 </li></ol></li></ol>
     </div>

--to=markdown
         annotation test
         1.  item 1
         ^M&nbsp;^M
         <p class="note">anno1</p>^M&nbsp;^M
         <p class="dothis">anno2</p>^M&nbsp;^M
         1.
             1.  item 11
         ^M&nbsp;^M
         <p class="note">anno3</p>^M&nbsp;^M
         1.
             1.  item 12
         ^M&nbsp;^M
         <p class="dothis">anno4</p>^M&nbsp;^M
         1.
             1.  item 13
btw, what are all these non-break-spaces "^M&nbsp;^M" for?

--to=markdown
         \begin{document}^M^M
         annotation test
         \begin{enumerate}
         \item  item 1
         \end{enumerate}
         \begin{note}

         anno1
         \end{note}

         \dothis{
         anno2
         }\begin{enumerate}
         \item \begin{enumerate}
         \item  item 11
         \end{enumerate}

         \end{enumerate}
         \begin{note}

         anno3
         \end{note}
         \begin{enumerate}
         \item \begin{enumerate}
         \item  item 12
         \end{enumerate}

         \end{enumerate}

         \dothis{
         anno4
         }\begin{enumerate}
         \item \begin{enumerate}
         \item  item 13
         \end{enumerate}

         \end{enumerate}
         ^M^M\end{document}^M


--to=text
         annotation test
         1.  item 1
         anno1
         anno2
         1.
                 1.  item 11
         anno3
         1.
                 1.  item 12
         anno4
         1.
                 1.  item 13

cheers -ben

On Tue, Jun 3, 2014 at 6:23 PM, Ben Coman <[hidden email]> wrote:

please. It is important to keep consistency here.



no idea. Ben, do you have an idea?


You did a great job. Thank you

--
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm."
Winston Churchill