Smalltalk › Pharo › Pharo Smalltalk Developers

PetitMarkdown

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

32 messages Options

Sven Van Caekenberghe-2

Re: PetitMarkdown

I am sorry, but I don't think you really have looked at this in detail. Read

http://en.wikipedia.org/wiki/Markdown

History & Extensions, just to known about some of the differences out there.

Any language without any formal spec is close to impossible to parse well, it is just hacking. Note that the original MD allows HTML inside ! WTF ?

But if it is so easy, please write your own parser. Many have tried, many have failed. Or go read the code of one of them.

Here is a cool attempt: http://www.greghendershott.com/2013/11/markdown-parser-redesign.html

The fact that github implements their own variant and made it convenient says nothing.

For the record, I am using MD myself.

> On 14 Apr 2015, at 23:11, Dmitri Zagidulin <[hidden email]> wrote:
>
> On Tue, Apr 14, 2015 at 4:10 PM, Sven Van Caekenberghe <[hidden email]> wrote:
>
> Furthermore, there is NO MarkDown standard, nor will there ever be. There are slight but annoying differences between the main implementors.
>
> Not true. There is at least http://spec.commonmark.org/
>
> It is super hard to write a parser for MD.
>
> What do you mean? Why?
>

demarey

Re: PetitMarkdown

In reply to this post by philippeback

Le 14 avr. 2015 à 22:51, [hidden email] a écrit :

> I hate the figures not going where I want due to the LaTeX generation in Pillar.

There should be options to place it where you want. Maybe a pillar expert could answer?

> As for class comments, markdown would make more sense to use when putting files under source control on git and then stored in github because filetree generates README.md files for such comments.
>
> It makes for a nice reading there. In that respect, Pillar class comments will be more of a nuisance than a help.

I don't agree. We can use pillar inside the image AND we can also generate a README.md file from pillar doc when useful.

> For generating web documentation, it is easier to provide markdown so that any web framework will be able to conver (e;g; Showdown.js and 2 lines of code).

We already have a pillar to MD converter.

We will have to deal with MD time to time but you do not necessarily have to adopt it. You just need to have a good way to interact with it.

smime.p7s (5K) Download Attachment

Damien Cassou

Re: PetitMarkdown

Christophe Demarey <[hidden email]> writes:

> Le 14 avr. 2015 à 22:51, [hidden email] a écrit :
>
>> I hate the figures not going where I want due to the LaTeX generation in Pillar.
>
> There should be options to place it where you want. Maybe a pillar expert could answer?

this is not possible and, in my opinion, not desired.

The following explains my reasons but requires some LaTeX knowledge to
be understood.

LaTeX does a really good job a placing figures at nice locations. For
example, if your paragraph ends with 2 lines at the top of a page and
you place a figure after this paragraph, LaTeX will make sure the figure
appears at the top of a page and not after the 2 lines: this is because
it would be ugly to have 2 lines, then a figure, then the rest of the
text.

In LaTeX, you have to make sure to always write things like "as can be
seen in Figure 3" instead of "as can be seen in the figure below"
because you can never be sure of the exact location of your figures.

Please note that if in Pillar you don't specify any label you could
reference from your text, then the figure will be placed by LaTeX at the
exact location where you put it in Pillar. This is because, in this
case, there is no way to write "as can be seen in Figure 3" when there
is no label.

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

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

philippeback

Re: PetitMarkdown

Le 16 avr. 2015 10:41, "Damien Cassou" <[hidden email]> a écrit :
>
>
> Christophe Demarey <[hidden email]> writes:
>
> > Le 14 avr. 2015 à 22:51, [hidden email] a écrit :
> >
> >> I hate the figures not going where I want due to the LaTeX generation in Pillar.
> >
> > There should be options to place it where you want. Maybe a pillar expert could answer?
>
> this is not possible and, in my opinion, not desired.
>
> The following explains my reasons but requires some LaTeX knowledge to
> be understood.
>
> LaTeX does a really good job a placing figures at nice locations. For
> example, if your paragraph ends with 2 lines at the top of a page and
> you place a figure after this paragraph, LaTeX will make sure the figure
> appears at the top of a page and not after the 2 lines: this is because
> it would be ugly to have 2 lines, then a figure, then the rest of the
> text.
>
> In LaTeX, you have to make sure to always write things like "as can be
> seen in Figure 3" instead of "as can be seen in the figure below"
> because you can never be sure of the exact location of your figures.
>
> Please note that if in Pillar you don't specify any label you could
> reference from your text, then the figure will be placed by LaTeX at the
> exact location where you put it in Pillar. This is because, in this
> case, there is no way to write "as can be seen in Figure 3" when there
> is no label.

Customer opinion on the output: why are figures not where I expect them to be?

Most of the figures are HD screenshots. Moving them around sucks.
I'll try the no label thing. But labels are useful.
HTML export is not doing that.
LaTeX is an interim tool to get the PDF output. Would it be possible to use Artefact instead?
LaTeX toolchain is *huge*.

Phil

>
>
> --
> Damien Cassou
> http://damiencassou.seasidehosting.st
>
> "Success is the ability to go from one failure to another without
> losing enthusiasm." --Winston Churchill
>

Stephan Eggermont-3

Re: PetitMarkdown

On 16/04/15 12:07, [hidden email] wrote:
> Customer opinion on the output: why are figures not where I expect them
> to be?
>
> Most of the figures are HD screenshots. Moving them around sucks.
> I'll try the no label thing. But labels are useful.
> HTML export is not doing that.
> LaTeX is an interim tool to get the PDF output. Would it be possible to
> use Artefact instead?

Not without creating extremely ugly documentation,
at the current state of Artefact layouting.
Line breaking is primitive, support for other than base-14
fonts is missing, pngs are rendered, not embedded.

> LaTeX toolchain is *huge*.

Yeah, it is. The best object model for documentation is that of
Framemaker. Current machines should be fast enough to run
something like that in Smalltalk instead of c now, 20 years later.

Stephan

Damien Cassou

Re: PetitMarkdown

In reply to this post by philippeback

[hidden email] <[hidden email]> writes:
> Customer opinion on the output: why are figures not where I expect them to
> be?

they are where the *reader* expects them to be :-). The author of TeX
thought that a machine can best decide where to put a figure because
when you write the TeX source you don't know where in the page a
particular figure will be placed when rendered as PDF: each time you add
a paragraph somewhere, you move everything after it.

> Most of the figures are HD screenshots. Moving them around sucks.

why?

> I'll try the no label thing. But labels are useful.

Labels (i.e., identifiers) are useful only when you reference a figure
from the text.

Captions (i.e., explaining texts) are useful to describe the figure.

> HTML export is not doing that.

yes, because HTML has not notion of page. PDF is very nice for printing
and LaTeX makes sure that figures are nicely placed on the paper. HTML
is not meant to be printed. If you print an HTML page, the result is
often ugly.

> LaTeX is an interim tool to get the PDF output. Would it be possible
> to use Artefact instead?

probably, but don't expect it to look nice because the (La)TeX authors
are experts in the domain and we are not. I already talked about that
with Olivier (on CC) and I think he agreed IIRC.

> LaTeX toolchain is *huge*.

agree.

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

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

Dmitri Zagidulin

Re: PetitMarkdown

In reply to this post by Damien Cassou

On Thu, Apr 16, 2015 at 4:40 AM, Damien Cassou <[hidden email]> wrote:

Please note that if in Pillar you don't specify any label you could
reference from your text, then the figure will be placed by LaTeX at the
exact location where you put it in Pillar. This is because, in this
case, there is no way to write "as can be seen in Figure 3" when there
is no label.

I tried that out in a recent UPBE chapter (here: https://github.com/SquareBracketAssociates/UpdatedPharoByExample/commit/f0b13888e759a6fb0d214699e27b87a270d35697#diff-a251fe30d553e30bb3c8e091a0280d90L480 ).

Didn't seem to work, the figure with no label was still placed arbitrarily by LaTeX (and not in the exact location). (And, actually, LaTeX placed the figure in the middle of a script block, which is really odd).

Is this an issue of the version of Pillar that the book's build tools are using?

Stephan Eggermont-3

Re: PetitMarkdown

On 18/04/15 18:49, Dmitri Zagidulin wrote:
> Didn't seem to work, the figure with no label was still placed
> arbitrarily by LaTeX (and not in the exact location). (And, actually,
> LaTeX placed the figure in the middle of a script block, which is really
> odd).

Not a LaTeX problem. Scripts should be generated so that they cannot
have orphans (or widows) and that includes the caption.

I want a WYSIWYG documentation system in Smalltalk. Something between
LaTeX and Framemaker.

Stephan

Damien Cassou-2

Re: PetitMarkdown

In reply to this post by Dmitri Zagidulin

Dmitri Zagidulin <[hidden email]> writes:

> Is this an issue of the version of Pillar that the book's build tools are
> using?

I thought I implemented that but you are right, it is not implemented.
If you are lucky, Cyril will see this thread and fix it (hint, it's in
PRLaTeXWriter>>writeEmbeddedPicture:).

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

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

Hannes Hirzel

Re: PetitMarkdown

In reply to this post by kurs.jan

Thank you Jan, for your work in enhancing PetitParser for Markdown. I
think I got what you did by loading PetitParser in Pharo 4.0.

I found the examples PPMarkdownGrammarTest, category testing-documents.

I also read http://scg.unibe.ch/research/indentParsing.

Could you please elaborate a bit more about the changes you did to the
grammar and give some more usage examples?

Regards

Hannes

On 4/14/15, Jan Kurš <[hidden email]> wrote:

> Hey,
>
> I also created an indentation sensitive extension of PetitParser, I also
> included some examples including Markdown. If you load PetitParser, you get
> the Markdown example as well.
>
> There is a short introduction to the indentation:
>
> http://scg.unibe.ch/research/indentParsing
>
> Cheers Jan
> On Apr 13, 2015 5:24 PM, "H. Hirzel" <[hidden email]> wrote:
>
>> Are there any news on this?
>>
>> --Hannes
>>
>> On 12/28/14, Norbert Hartl <[hidden email]> wrote:
>> > I found markdown parsers in smalltalkhub and in the configuration
>> browser.
>> >
>> > http://smalltalkhub.com/#!/~PharoExtras/PetitMarkdown/
>> > <http://smalltalkhub.com/#!/~PharoExtras/PetitMarkdown/>
>> >
>> > and the one in the configuration browser
>> >
>> > PPMarkdown
>> >
>> > If I understand it correctly both are rooted into work Camillo did. The
>> one
>> > in PharoExtras looks newer to me. So I assume the best would be to copy
>> the
>> > ConfigurationOfPetitMarkdown from PharoExtras to MetacelloRepo and
>> > remove
>> > the ConfigurationOfPPMarkdown. Right? Or are there any objections?
>> >
>> > Norbert
>>
>>
>

kurs.jan

Re: PetitMarkdown

Hi Hannes,

I actually did not do any changes to the grammar, I wrote the grammar from scratch. The reason I did so was to have a proof of concept of my PetitParser extension for parsing indentation-sensitive grammars such as Markdown or Python.

The most simplest example you can do is to evaluate following:

PPMiniCommonMark new parse: '
# Heading

- list item
- second list item
'
As a result, you will get HTML fragment, that corresponds to one heading and list of items. All the supported CommonMark syntax is covered in the tests, so what you don't see in the test, has to be implemented.

CommonMark is kind of beast to parse, I had to do one big extension to parse it. It is to introduce the indentation stack (as described in http://scg.unibe.ch/research/indentParsing). You can see the indentation stack manipulation in PPMiniCommonMark rules such as: #prefix, #quoteBegin, #quoteEnd, #itemBullet and #itemEnd.

Cheers,

Jan

On 3 May 2015 at 08:46, H. Hirzel <[hidden email]> wrote:

Thank you Jan, for your work in enhancing PetitParser for Markdown. I
think I got what you did by loading PetitParser in Pharo 4.0.

I found the examples PPMarkdownGrammarTest, category testing-documents.

I also read http://scg.unibe.ch/research/indentParsing.

Could you please elaborate a bit more about the changes you did to the
grammar and give some more usage examples?

Regards

Hannes

On 4/14/15, Jan Kurš <[hidden email]> wrote:
> Hey,
>
> I also created an indentation sensitive extension of PetitParser, I also
> included some examples including Markdown. If you load PetitParser, you get
> the Markdown example as well.
>
> There is a short introduction to the indentation:
>
> http://scg.unibe.ch/research/indentParsing
>
> Cheers Jan
> On Apr 13, 2015 5:24 PM, "H. Hirzel" <[hidden email]> wrote:
>
>> Are there any news on this?
>>
>> --Hannes
>>
>> On 12/28/14, Norbert Hartl <[hidden email]> wrote:
>> > I found markdown parsers in smalltalkhub and in the configuration
>> browser.
>> >
>> > http://smalltalkhub.com/#!/~PharoExtras/PetitMarkdown/
>> > <http://smalltalkhub.com/#!/~PharoExtras/PetitMarkdown/>
>> >
>> > and the one in the configuration browser
>> >
>> > PPMarkdown
>> >
>> > If I understand it correctly both are rooted into work Camillo did. The
>> one
>> > in PharoExtras looks newer to me. So I assume the best would be to copy
>> the
>> > ConfigurationOfPetitMarkdown from PharoExtras to MetacelloRepo and
>> > remove
>> > the ConfigurationOfPPMarkdown. Right? Or are there any objections?
>> >
>> > Norbert
>>
>>
>

Hannes Hirzel

Re: PetitMarkdown

Hi Jan,

Thank you for your answer, in particular the PPMiniCommonMark example.

For me this is an interesting work, I can see a lot lot of application
areas in and out of the Pharo context. I'll have a closer look at your
implementation, in particular the test cases.

Have a good day

Hannes

On 5/3/15, Jan Kurš <[hidden email]> wrote:

> Hi Hannes,
>
> I actually did not do any changes to the grammar, I wrote the grammar from
> scratch. The reason I did so was to have a proof of concept of my
> PetitParser extension for parsing indentation-sensitive grammars such as
> Markdown or Python.
>
> The most simplest example you can do is to evaluate following:
>
> PPMiniCommonMark new parse: '
> # Heading
>
> - list item
> - second list item
> '
> As a result, you will get HTML fragment, that corresponds to one heading
> and list of items. All the supported CommonMark syntax is covered in the
> tests, so what you don't see in the test, has to be implemented.
>
> CommonMark is kind of beast to parse, I had to do one big extension to
> parse it. It is to introduce the indentation stack (as described in
> http://scg.unibe.ch/research/indentParsing). You can see the indentation
> stack manipulation in PPMiniCommonMark rules such as: #prefix, #quoteBegin,
> #quoteEnd, #itemBullet and #itemEnd.
>
> Cheers,
> Jan
>
> On 3 May 2015 at 08:46, H. Hirzel <[hidden email]> wrote:
>
>> Thank you Jan, for your work in enhancing PetitParser for Markdown. I
>> think I got what you did by loading PetitParser in Pharo 4.0.
>>
>> I found the examples PPMarkdownGrammarTest, category testing-documents.
>>
>> I also read http://scg.unibe.ch/research/indentParsing.
>>
>> Could you please elaborate a bit more about the changes you did to the
>> grammar and give some more usage examples?
>>
>> Regards
>>
>> Hannes
>>
>> On 4/14/15, Jan Kurš <[hidden email]> wrote:
>> > Hey,
>> >
>> > I also created an indentation sensitive extension of PetitParser, I
>> > also
>> > included some examples including Markdown. If you load PetitParser, you
>> get
>> > the Markdown example as well.
>> >
>> > There is a short introduction to the indentation:
>> >
>> > http://scg.unibe.ch/research/indentParsing
>> >
>> > Cheers Jan
>> > On Apr 13, 2015 5:24 PM, "H. Hirzel" <[hidden email]> wrote:
>> >
>> >> Are there any news on this?
>> >>
>> >> --Hannes
>> >>
>> >> On 12/28/14, Norbert Hartl <[hidden email]> wrote:
>> >> > I found markdown parsers in smalltalkhub and in the configuration
>> >> browser.
>> >> >
>> >> > http://smalltalkhub.com/#!/~PharoExtras/PetitMarkdown/
>> >> > <http://smalltalkhub.com/#!/~PharoExtras/PetitMarkdown/>
>> >> >
>> >> > and the one in the configuration browser
>> >> >
>> >> > PPMarkdown
>> >> >
>> >> > If I understand it correctly both are rooted into work Camillo did.
>> The
>> >> one
>> >> > in PharoExtras looks newer to me. So I assume the best would be to
>> copy
>> >> the
>> >> > ConfigurationOfPetitMarkdown from PharoExtras to MetacelloRepo and
>> >> > remove
>> >> > the ConfigurationOfPPMarkdown. Right? Or are there any objections?
>> >> >
>> >> > Norbert
>> >>
>> >>
>> >
>>
>>
>