Hi Gour,
It seems that I have some similar quest to you, so I will try to answer
about my approximation to documentation in the Pharo worl, even with the
existance of Pillar (but being by no means any kind of expert on it, and
of course this is my own experience, your mileage may vary).
On 25/12/15 11:02, Saša Janiška wrote:
Hiya,
I see that Pharo project has embraced Pillar system for documentation
purposes and my first question was "Why Pillar?" since, iirc, comparison
was made with e.g Markdown which is, obviously, not sufficient for eg.
authoring books, but there are more capable markups with 'standard'
implementations like rst/Sphinx and Asciidoc(tor).
Then I thought it must be some deeper reason, iow. something suitable to
work more closely with Pharo itself.
Now I have two questions:
1) Can someone answer in more detail "Why Pillar?" and
Seems that the reasons exposed in this tread are: It predated markdown,
so was already used inside the community, and gives us finer control on
the overall markup language, including exporting formats. I have tested
several light markup languages for documentation including markdown,
reST, AsciiDoc, dokuwiki, wikimedia, tiddly wiki, text2tags (t2), among
others. There are several features that are desirable in many of them,
like nice evoking notations of t2t and dokuwiki, wide support for
exporting formats of reST, readability of AsciiDoc regarding extending
features, the spread of Media wiki or nice modular approach to
documentation of tiddly wiki. Surely the two reasons for pillar are also
good ones. How do you balance this options?
Before reentering Pharo I was thinking in something like an extensible
light markup language, like t2t, but instead of using regular expression
(t2t uses them), it would use something like yaml[1] and a processor of
these serialized data for different exporters. The idea of combining
light markup languages for documentation and data serialization seems to
become more popular these days. Two projects implement this idea
Pandoc[2] and Grav[3] and both use a combination of markdown and yaml.
[1] https://en.wikipedia.org/wiki/YAML
[2] http://pandoc.org/
[3] http://getgrav.org/
So, how this could be combined with the offerings of Pharo? My bet is on
pandoc (markdown+yaml) for writing almost anything, with some advantages
over pillar:
a. It has a bigger momentum with projects like scholarly markdown ([4]
http://scholmd.org/)
b. It has support for bibliographic references, footnotes a a more
complete feature set.
The finer control would be offered by using abstract syntax trees (AST)
for more detailed manipulation, which is already used to extend pandoc
with languages like ruby, lua, perl (see examples in [5]
http://pandoc.org/scripting.html) and could be used, theoretically with
Pharo. That's where metamodels used by Pillar could be used, so we could
extend pandoc inside Pharo, while using markdown + yaml as a common
language to write prose with other authors beyond this community,
because Pillar is used only here, while markdown is becoming more used
as a cross-community language for documentation, including Jupyter
notebooks that combine documentation with languages like R, Julia,
Haskell or Python.
This lead me to your next point:
2) For some time I was considering whether to settle on using rst or
AsciiDoc for *all* my writings, which means blog posts, my study notes,
preparing books, writing articles etc.
Since I've settled to use Python-powered static-site-generator (Nikola)
along with reStructuredText markup which can call external 'compilers'
to process blog posts written in specific markup, I wonder if it would
be possible to use Pillar markup with it since it seems there is cli for
it?
I have been using Nikola myself and keeping myself under a more cohesive
python environment for making my publishing and scripting/programming
exploration. That changed after knowing Pharo/Roassal/Moose and now I
try to "live inside" these technologies most of the time for my own
interactive documentation and visualization project[6] and connect with
the external world via standards & formats like Json, cvs, yaml and
markdown. That's why now I'm using grav instead of Nikola for my web
publishing. Ecstatic have more powerful things like a logic-less
approach to templating via mustache, that is neutral to the underlaying
language, while grav templating is tied to php, but grav seems more
developed and with more ready to use templates or skeletons for web
publishing, so, once installed, you barely touch any underlaying
technology beyond markup languages. More details on the
transition/combination of grav/nikola can be found on [7].
[6] http://mutabit.com/grafoscopio/index.en.html
[7] http://mutabit.com/offray/blog/es/entry/2015-10-06-grav-nikola-both
So, while I think that choosing Pharo technologies is better for making
them more mature, tested and used, I also think that is important to
choose proper balance to know which combination of Pharo technologies
and external ones is adequate. That depends on each user. In my case,
living inside Pharo for almost anything and choosing markdown + yaml for
writing and publishing (via pandoc and grav) have worked very well and
could be a working combination for you also. That doesn't preclude
further exploration and use of other related Pharo technologies like
Pillar and Ecstatic, but this could be made in the future via
metamodels/ASTs or as a way to extend/modify the way Pharo interacts or
integrates with the external world... well I'm getting kind of
philosophical here, but that would be my middle term approach on
publishing and markup languages.
Cheers,
Offray
Ps: Would you mind to share more details about your project. The
questions you're asking for it are pretty interesting.
