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."
