Thank Tim,
My primary reason to submit the message was not to necessarily persuade
you per se. But to provide something historical for the mailing list as
this can be a recurring subject. Why use Pillar markup instead of
???(insert personal favorite).
If Pharo were to decide on a different markup language. The question
would still be which one, why and then how do we proceed. Then our
extensions may not be accepted by the greater body of users of said
markup. We would still be contributing to the fragmentation of markup.
As far as familiarity, I don't know. And familiarity with what. I do not
find that reStructuredText to be similar to Markdown.
It would stop people from asking why we aren't using Markdown. But it
wouldn't prevent others. Why aren't we using GFM Markdown, or Kramdown
or Commonmark or ...? Why aren't we using YAML or reST or AsciiDoc or
insert latest greatest creation markup or current flavor of the moment.
Which is why I wanted to point out that there is no consensus among
users of markup languages. At least I do not see one. Nor do I believe
that we have seen the end of creation of new markup languages.
I understand the difficulty, though I do not suffer from it as I have
not mastered any of those other languages. I have been using
Squeak/Pharo for a long time. I struggle when I look at those other
languages. To me they are the foreign ones.
And I do not see these emerging standards you refer to. When we see
Python, Ruby, Perl, C++, various projects, etc. communities having
consensus on a common markup for documentation. Then I see an emerging
standard. Until then it seems to possibly be an emerging standard for a
particular markup language which is among the set of markup languages.
If we were the only language and development environment doing our own
thing. Then we might have a very good reason to talk. But we are not.
Python with its enormous community does its own thing. I don't know that
other languages have a consensus for markup for documentation except for
Python and Pharo.
While writing this email I went and discovered that even GitHub is not
dogmatic about the subject. Obviously they have an opinion. But they
permit multiple markup languages. Quite possibly someone could write a
Pillar tool for GitHub to use and then we could just submit
Readme.pillar for our projects. :)
https://github.com/github/markup
Shows that GitHub allows for .markdown, .mdown, .mkdn, .md; .textile;
.rdoc; .org; .creole; .mediawiki, .wiki; .rst; .asciidoc, .adoc, .asc;
.pod. So it seems that there are many communities on GitHub who prefer
their own markup and tools.
We could possibly write the Pillar tool for GitHub or an exporter to the
preferred markup language of the above.
This author provides arguments for using reStructuredText over Markdown
for GitHub documents. Citing deficiencies in Markdown and expressiveness
in reST.
https://gist.github.com/dupuy/1855764
So again. I am just not seeing a consensus around any emerging standard
for "the markup language".
At the same time if you are desirous of writing in Commonmark in your
text editor. Can you not write conversion software that goes from
Commonmark to Pillar? Thus, meeting want you want and what we require?
If you were to do so, you would definitely have a good understanding of
the differences in philosophy and capabilities of each. Just a thought.
Any way, thanks for engaging in the conversation. I wasn't targeting you
personally, but rather the topic. You are not alone in your thinking.
The Pharo community is not alone in its thinking either.
Thanks.
Jimmie
On 08/14/2017 11:34 AM, Tim Mackinnon wrote:
Jimmie et al. nicely reasoned arguments - and Doru's point about
controlling the syntax is an interesting one that I hadn’t thought about.
Personally, I find having too many similar syntax’s confusing -
contributing to things is hard enough - having to remember that its !!
Instead of ## and “” instead of ** is just frustrating for me.
My vote would be what Peter suggested - use
http://spec.commonmark.org/0.28/ and put our Pillar extensions back on
top for things that Stef was mentioning. (I think that’s what I’ve
understood gfm markdown is).
Sure, maybe we were first with Pillar, but for me, lots of programming
is in other languages, and I use Smalltalk where I can, and a hybrid
of multiple languages and projects is often the reality - so a lowest
common denominator of Markdown is just easier. The fact that we are
quite close to what our colleagues in other languages use (regardless
of what Python has chosen), is quite interesting.
That said, if the community wants to stick to its gun’s thats fine - I
will probably still investigate how to use Commonmark for myself, and
will still contribute to Pillar docs where I can (and curse history) -
but I think we are long better off trying to join emerging standards
where we can particularly if they aren’t our core language thing. And
it just makes it less frictionless for ourselves and newcomers.
Of course, if we were to move, we would need to translate a lot of
quality docs to a new format - but I would be up for contributing to
that if that was a deciding factor.
Tim
On 14 Aug 2017, at 16:41, Jimmie Houchin <jlhouc...@gmail.com
<mailto:jlhouc...@gmail.com>> wrote:
TL;DR
Main points:
Their is no universally accepted markup language.
Other communities use their own markup and tools and their markup
and tools choice is not determine by other communities decisions.
We need a language and tool chain that we can control and maintain
which accomplishes our goals.
Our language and tools already exist and have existed for longer than
most of the other markup languages. Of course they existed in various
different forms over the years and have evolved into what they
currently are.
It might be nice to have a GFM Markdown exporter from Pillar for
GitHub projects.
I just want to comment on the fact that there is no universal markup
language that every development community has settled upon. Making
Markdown or some variant the markup language for Pharo only aligns us
with a certain part of the development community. Even Markdown is
not unified as is evident by the discussion.
It is true that GitHub uses their variant of Markdown. And as long as
we use GitHub we will need to use their variant for documents that
reside on their system.
However as a significant counter example to lets all use gfm
Markdown, is the Python community and their documentation.
https://docs.python.org/devguide/documenting.html
"""
7. Documenting Python
The Python language has a substantial body of documentation, much of
it contributed by various authors. The markup used for the Python
documentation is reStructuredText, developed by the docutils project,
amended by custom directives and using a toolset named Sphinx to
post-process the HTML output.
This document describes the style guide for our documentation as well
as the custom reStructuredText markup introduced by Sphinx to support
Python documentation and how it should be used.
The documentation in HTML, PDF or EPUB format is generated from text
files written using the reStructuredText format and contained in the
CPython Git repository.
"""
So the Python community uses their own markup language and their own
tool chain. So therefore, it is not wrong for a community to go their
own way, for their own reasons. Even within the conventional file
based languages such as Python.
The fact that you have tools such as Pandoc, suggest that there is
not true uniformity or unanimity among developers as to the best
markup language or tool chain.
I believe that a language that we can control and maintain is better
than adopting some other foreign markup language that is neither
better, nor unanimously used by all. That would ultimately
potentially require extensions to accomplish our goals. Then we would
be maintaining someone else's language with our extensions that may
or may not be accepted by the larger community. This does not prevent
but rather encourages fragmentation of the existing Markdown.
Regardless, Pillar markup already exists. The tools in Pharo already
understand it. Should someone desire to use Pharo which is far more
different from Python/Ruby/etc. than Pillar syntax is from Markdown.
Then it should be worth their effort to learn our tools.
Pillar markup is older than Markdown, etc. It's history begins in
SmallWiki. It isn't as if we jumped up and decided to create
something new in order to be different. Our markup and tools are
older. They (and others) are the ones that decided to do their own
markup and tools. And it is okay that they did so. Nothing wrong with
doing so. Every community has the right to what they believe is best
for their community. Even if other communities disagree.
The ability to control and maintain is highly valuable. We can
understand what our requirements are for today. But we can not know
what the requirements are in the future. Nor can we know that
Markdown or whomever will have such requirements when they appear. It
is easy to see in the beginning with the Squeak Wiki syntax to the
now Pillar syntax, changes that have been made to accommodate new
requirements as they became known. We need to maintain that ability.
Sure we would reserve the right to do so in any language we adopt.
But the then current standard bearer of said language would determine
whether what we do is acceptable and incorporate or whether we are
then in fact adding to their fragmentation. Pillar is ours. There is
not fragmentation when we evolve.
However, since we have made a decision to use GitHub and GitHub has
made a decision to use their own GFM Markdown. It might be nice to
have a GFM Markdown exporter from Pillar for GitHub projects. This
way we can use our own tools and markup language to accomplish
whatever we want to accomplish. Including generating a Readme.md for
our GitHub projects.
Just wanted to toss out this simple opinion and facts about the
situation.
Jimmie
On 08/14/2017 04:10 AM, Tudor Girba wrote:
Hi Tim,
The main benefit of relying on Pillar is that we control its syntax
and can easily extend it for our purposes. Also, there was quite a
bit of engineering invested in it, and even though we still need to
improve it, there exists a pipeline that allows people to quickly
publish books.
The figure embedding problem is one example of the need to customize
the syntax and behavior, but this extensibility will become even
more important for supporting the idea of moving the documentation
inside the image. For example, the ability to refer to a class,
method or other artifacts will be quite relevant soon especially
that the editor will be able to embed advanced elements inside the text.
Cheers,
Doru
On Aug 14, 2017, at 10:46 AM, Tim Mackinnon <tim@testit.works> wrote:
Hi Stef - I think your’s is a fair requirement (in fact I hit
something similar when doing a static website using a JS markdown
framework - and this is why I mentioned Kramdown which adds a few
extras to regular markdown - but it feels like it goes a bit too far).
My next item on my learning todo list was to try and replace that
JS generator with something from Smalltalk - so I think we can
possibly come up with something that ticks all the right boxes (I’d
like to try anyway).
I’ll keep working away on it and compare notes with you. I think
with Pillar, it was more that things like headers, bold and italics
are similar concepts but just use different characters - so I keep
typing the wrong thing and getting frustrated particularly when we
embrace Git and readme.md is in markdown.
Tim
On 13 Aug 2017, at 20:08, Stephane Ducasse
<stepharo.s...@gmail.com> wrote:
Hi tim
I personally do not care much about the syntax but I care about what I
can do with it
(ref, cite, ... )
I cannot write books in markdown because reference to figures!!!!!!
were missing.
And of course a parser because markdown is not really nice to parse
and I will not write a parser because I have something else to do. I
want to make pillar smaller, simpler, nicer.
Now if someone come up with a parser that parse for REAL a markdown
that can be extended with decent behavior (figure reference, section
reference, cite) and can be extended because there are many things
that can be nice to have (for example I want to be able to write the
example below) and emit a PillarModel (AST) we can talk to have
another syntax for Pillar but not before.
[[[test
2+3
5
]]]
and being able to verify that the doc is in sync.
Stef
On Sat, Aug 12, 2017 at 12:37 AM, Tim Mackinnon <tim@testit.works>
wrote:
Of course, I/we recognise and appreciate all the work that's gone
into docs in pillar - but I think it should be reasonably
straightforward to write a converter as it is pretty closely
related from what I have seen.
So I don't make the suggestion flippantly, and would want to help
write a converter and get us to a common ground where we can
differentiate on the aspects where we can excel.
Tim
Sent from my iPhone
On 11 Aug 2017, at 23:21, Peter Uhnak <i.uh...@gmail.com> wrote:
A long time issue with Markdown was that there was no
standardization (and when I used Pillar's MD export ~2 years ago
it didn't work well).
However CommonMark ( http://spec.commonmark.org/0.28/ ) has
become the de-facto standard, so it would make sense to support
it bidirectionally with Pillar.
The readme.md that Peter is talking about is gfm markdown
Well, technically it is just a CommonMark, as I am not using any
github extensions.
(Github uses CommonMarks and adds just couple small extensions.)
Peter
--
www.tudorgirba.com
www.feenk.com
“Live like you mean it."
