Some should cool down.

I am using Pillar to write my (internal) docs.

And I use markdown too.

Both have their uses.

Compared to things like RMarkdown, knitr, and RPubs in the R community, what we do have is passable in terms of output. We have a small community, we have to deal with that fact.

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

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.

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

Furthermore, a lot of Pillar files embed non pillar markup for special things.

For me, Pillar is for the books. And speciality applications that use the visitors to produce other stuff (among which Markdown).

As for writing stuff, I do md and pillar files in Vim. So much for specific tools that weren't satisfying when writing. Too slow, too cumbersome, not enough power for editing (compared to Vim, yeah, nothing comes close in terms of speed once you know the tricks).

Phil

On Tue, Apr 14, 2015 at 10:03 PM, Dmitri Zagidulin <dmitri@zagidulin.net> wrote:

Whoa.��
I genuinely don't understand the fierce emotions here. Why do Pillar and Markdown have to be opposed? Why is wanting support for better parsing of MD (a commonly used format around the web, and useful in many projects) somehow an insult to the work done on Pillar?

(Incidentally, I don't quite understand why Pillar was created in the first place. Why have a slightly different and incompatible markdown format from what the rest of the world is using? But that's not the point. We have both, and it's easy to support both. What's the problem?)

On Tue, Apr 14, 2015 at 3:08 PM, stepharo <stepharo@free.fr> wrote:

I'm really pissed off. Because nearly nobody tried to write anything with pillar and you just talk
about what you do not know.�� But thanks this is great to see that we are spending our energy for people
who will never even try to use what we are doing.
Superb!

No need to reply I will not read this thread anymore. And I should not even have because it was so obvious.

And yes I 'm REALLY pissed off. You should also say to cyril that what is is doing is hopeless because as soon
as we will have a stupid markdown parser suddenly it will be great. what a shit.

So go and write your documentation in any format and do not expect me to look at it.
I'm fed up about people that want doc on the web and when we spend time to migrate from latex to
pillar to generate html and latex do not even consider what we did.

Stef

I would prefer pillar for class / packages comments

I was quite surprised there are any MD defendants considering the pillar push. But since diversity is (often) a good think maybe having something like gt-inspector there would be cool where you can add this in whatever format you want. (And maybe one day someone will write pillar to morphic/whatever converter and it would be even cooler.)

It is a difficult topic. I agree with anyone that MarkDown is not a good format for parsing. Pillar is the right thing to do here. But there is one point of MarkDown that is hard to beat. A MarkDown text is always good to read, eben while writing. In something like a class comment it would be easy to use. What we don't want is to write system documentation in a format that you need to convert first before you can see the result. It is either having a wysiwyg editor for those things with pillar below or a simple format that can both.

my 2 cents,

that��s actually my main point too, yes.��

Esteban

norbert