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
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

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
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

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
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

Damien Cassou wrote:
Thats fine. It was not strong conviction, just a choice that needed to
be made one way or the other.

> I like your solution of using the "class" parameter in HTML.
> The same should apply in LaTeX.

Yes. I am doing something similar. btw, is it a strong convention that
Tex commands and environments are all lowercase? That is, should I force
the annotation label in "\begin{note}" to lowercase, or should I pass
that through unchanged.

 > For Markdown, we should probably have the same solution as for HTML.

I had a hunt around and it seems that Markdown doesn't support paragraph
styles.  And the workaround specified here...
http://stackoverflow.com/questions/1058933/can-i-define-a-class-name-on-paragraph-using-markdown

apparently does not work on github...
https://github.com/github/markup

But Hey! Check this out...
https://github.com/github/markup/blob/master/CONTRIBUTING.md

Maybe we could add a Pillar-->HTML processor to Github?
"If your markup is in a language other than Ruby, drop a translator
script in lib/github/commands which accepts input on STDIN and returns
HTML on STDOUT..."
https://github.com/github/markup/blob/master/lib/github/markups.rb


> For text, I think the annotation
> should have no impact on the output (just as it is now).

> What do you think?
>

So it seems that Text and Markdown cannot produce different formatted
paragraphs.  In those two cases, I still lean towards putting the
annotation label in the output, but I'm happy enough to leave it out.

cheers -ben
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

On Sun, Jun 1, 2014 at 6:10 PM, Ben Coman <[hidden email]> wrote:
> Yes. I am doing something similar. btw, is it a strong convention that Tex commands and environments are all lowercase? That is, should I force the annotation label in "\begin{note}" to lowercase, or should I pass that through unchanged.


I think you should not change anything. Is it up to the writer to do
something not stupid.

> > For Markdown, we should probably have the same solution as for HTML.
>
> I had a hunt around and it seems that Markdown doesn't support paragraph styles.  And the workaround specified here...
> http://stackoverflow.com/questions/1058933/can-i-define-a-class-name-on-paragraph-using-markdown
>
> apparently does not work on github...
> https://github.com/github/markup

in pillar we have both Markdown and GithubMarkdown as export options.
So we can have a solution dedicated to github if required.


> But Hey! Check this out...
> https://github.com/github/markup/blob/master/CONTRIBUTING.md
>
> Maybe we could add a Pillar-->HTML processor to Github?


There should not be any technical problem to do that. Do you want to
try? I can help if you have problems.


> "If your markup is in a language other than Ruby, drop a translator script in lib/github/commands which accepts input on STDIN and returns HTML on STDOUT..."
> https://github.com/github/markup/blob/master/lib/github/markups.rb
>
>
> So it seems that Text and Markdown cannot produce different formatted paragraphs.

for text it is clear. For Markdown I'm still not sure if it is
possible or not. Maybe a <div class=<annotation>> would work.


> In those two cases, I still lean towards putting the annotation label in the output, but I'm happy enough to leave it out.


for text I think we should not change the current export. For
Markdown, I leave the decision to you.


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

"Success is the ability to go from one failure to another without
losing enthusiasm."
Winston Churchill
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

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
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

Damien Cassou wrote: HI Damien,

After adding PRLaTeXWriter>>visitAnnotatedParagraph:, to make the build
green I made the following modifications to PFTE.

FILE: CalculatorTutorial/CalculatorTutorial.pier
LaTeX Error: Environment  undefined  "\begin{}"
-@@ TODO
+@@todo
Removed the space after the '@@' and changed todo to lowercase.   Maybe
I should have been changed it to a %todo comment, since now it looks
like attached file Book-todo.


FILE: ComparingSolutions/ComparingSolutions.pier
LaTeX Error: Environment comment@@ undefined
-@@comment@@ May be you should give one example of an ODE and
+@@comment May be you should give one example of an ODE and

LaTeX Error: Environment comment: undefined
-@@comment: may be you should split the methods with an initialize phase
-@@comment: I simplified the code. If you want I can do a code review
+@@comment may be you should split the methods with an initialize phase
+@@comment I simplified the code. If you want I can do a code review

LaTeX Error: Environment we undefined
-@@we can use the configuration form to load. To verify
+@@note we can use the configuration form to load. To verify

-----
Now I notice...
https://github.com/pillar-markup/pillar-documentation#32-paragraphs-and-framed-paragraphs
says:
> An empty line starts a new paragraph.
> An annotated paragraph starts a line with @@ followed by either todo or note. For example,
> @@note this is a note annotation.
> generate
>   Note: this is a note annotation.

But this is no longer the case.  As advised I changed it so that Pillar
does not hardcode output "Note:".

Actually common.tex does define the 'note' environment to show "Note:" -
but that is configurable without changing the Pillar code.

Also, annotations are no longer restricted to just @todo or @@note.  Any
annotation can be used so long as a matching environment/style is defined.

So I will update that in the doc.

Also, it says:
> @@todo this is a todo annotation
> generates a todo annotation that is not visible in the output.

This is no longer the case as I removed this.  This was only being done
in PRMarkdownWriter, and I did not see the point over using %todo. Can
you confirm that is reasonable? Or did I miss some purpose.

After your reply, I will update that also in the doc.

cheers -ben

_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

Ben Coman wrote:

Damien Cassou wrote:

On Sun, Jun 1, 2014 at 6:10 PM, Ben Coman[hidden email]  wrote:

Yes. I am doing something similar. btw, is it a strong convention that Tex commands and environments are all lowercase? That is, should I force the annotation label in "\begin{note}" to lowercase, or should I pass that through unchanged.

I think you should not change anything. Is it up to the writer to do
something not stupid.

For Markdown, we should probably have the same solution as for HTML.

I had a hunt around and it seems that Markdown doesn't support paragraph styles.  And the workaround specified here...
http://stackoverflow.com/questions/1058933/can-i-define-a-class-name-on-paragraph-using-markdown

apparently does not work on github...
https://github.com/github/markup

in pillar we have both Markdown and GithubMarkdown as export options.
So we can have a solution dedicated to github if required.

But Hey! Check this out...
https://github.com/github/markup/blob/master/CONTRIBUTING.md

Maybe we could add a Pillar-->HTML processor to Github?

There should not be any technical problem to do that. Do you want to
try? I can help if you have problems.

"If your markup is in a language other than Ruby, drop a translator script in lib/github/commands which accepts input on STDIN and returns HTML on STDOUT..."
https://github.com/github/markup/blob/master/lib/github/markups.rb


So it seems that Text and Markdown cannot produce different formatted paragraphs.

for text it is clear. For Markdown I'm still not sure if it is
possible or not. Maybe a<div class=<annotation>>  would work.

In those two cases, I still lean towards putting the annotation label in the output, but I'm happy enough to leave it out.

for text I think we should not change the current export. For
Markdown, I leave the decision to you.

HI Damien,

After adding PRLaTeXWriter>>visitAnnotatedParagraph:, to make the build green I made the following modifications to PFTE.

FILE: CalculatorTutorial/CalculatorTutorial.pier
LaTeX Error: Environment  undefined  "\begin{}"
-@@ TODO
+@@todo
Removed the space after the '@@' and changed todo to lowercase.   Maybe I should have been changed it to a %todo comment, since now it looks like attached file Book-todo.


FILE: ComparingSolutions/ComparingSolutions.pier
LaTeX Error: Environment comment@@ undefined
-@@comment@@ May be you should give one example of an ODE and
+@@comment May be you should give one example of an ODE and

LaTeX Error: Environment comment: undefined
-@@comment: may be you should split the methods with an initialize phase
-@@comment: I simplified the code. If you want I can do a code review
+@@comment may be you should split the methods with an initialize phase
+@@comment I simplified the code. If you want I can do a code review

LaTeX Error: Environment we undefined
-@@we can use the configuration form to load. To verify
+@@note we can use the configuration form to load. To verify

-----
Now I notice...
https://github.com/pillar-markup/pillar-documentation#32-paragraphs-and-framed-paragraphs
says:

An empty line starts a new paragraph.
An annotated paragraph starts a line with @@ followed by either todo or note. For example,
@@note this is a note annotation.
generate
  Note: this is a note annotation.

But this is no longer the case.  As advised I changed it so that Pillar does not hardcode output "Note:".

Actually common.tex does define the 'note' environment to show "Note:" - but that is configurable without changing the Pillar code.

Also, annotations are no longer restricted to just @todo or @@note.  Any annotation can be used so long as a matching environment/style is defined.

So I will update that in the doc.

Also, it says:

@@todo this is a todo annotation
generates a todo annotation that is not visible in the output.

This is no longer the case as I removed this.  This was only being done in PRMarkdownWriter, and I did not see the point over using %todo. Can you confirm that is reasonable? Or did I miss some purpose.

After your reply, I will update that also in the doc.

cheers -ben

---

_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

Can you let me know if there is anything stopping moving #stable forward to the latest packages, so that ./download.sh can pick it up.  Then I can push my PharoLaserGame tutorial updates that depend on them.

cheers -ben

_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

On Wed, Jun 4, 2014 at 6:03 PM, Ben Coman <[hidden email]> wrote:
> This is no longer the case as I removed this.  This was only being done in
> PRMarkdownWriter, and I did not see the point over using %todo. Can you
> confirm that is reasonable? Or did I miss some purpose.


you are reasonable :-). Thank you very much for all your changes.

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

"Success is the ability to go from one failure to another without
losing enthusiasm."
Winston Churchill
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki

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
_______________________________________________
Magritte, Pier and Related Tools ...
https://www.iam.unibe.ch/mailman/listinfo/smallwiki