Nice answer Norbert - I agree with the sentiment.
On Mon, 3 Aug 2020, at 9:01 AM, Norbert Hartl wrote:
> Sean,
>
> > Am 01.08.2020 um 20:23 schrieb Sean P. DeNigris <s...@clipperadams.com>:
> >
> > I wonder whether/how-best to apply our principle of minimalism when it
> > applies to areas of the system that, while critical, seem inherently
> > non-minimalist e.g. test harnesses, documentation, etc.
> >
> > I thought a lot about this when trying to document and refactor SDL. The
> > lack
> > of a mock library in core was a big barrier to understanding the
> > interactions between SDL objects. Maybe I'm being naive, but I feel like if
> > someone wants a minimal image, they're not going to want to load SUnit or
> > rich text documentation *at all*, so I don't see the risk-benefit of
> > crippling these features.
> >
> > This also applies to Pillar/Microdown. While *any* rich text comments are an
> > exciting development, I'd like to understand the benefit of Microdown vs.
> > full Pillar syntax.
> > Presumably the primary benefit is the size of the codebase. Any other
> > reasons?
> > A few other questions about the "rich text doc" roadmap:
> > 1. Could/will this be extended to method comments? That would be really
> > cool
> > :)
> > 2. How close are we for someone to use full Pillar syntax in class comments
> > in their own library? Any plans to make this possible?
> > NB. I originally posted a version of this on an older thread about Pillar
> > but and I'm assuming it may have gotten lost in that limited context.
> >
> The discussion about markup is a long one we keep doing for years. I
> personally don't like the pillar syntax too much and I don't see a big
> reason to keep it. On the other hand markdown is the de facto standard
> of simple formatting things. It is true that it is hard to parse
> because the syntax is not well thought.The point being positive about
> markdown is that it reads well in raw/ascii form and can be parsed into
> a document model to enable rich text variants like HTML, PDF, etc.
> And it plays well with the minimalist approach. Because markdown is
> readable in its raw form it can be used without all of the rich text
> rendering code loaded. So the goal is to have a pleasant approach to
> documentation for your big development image. You can make a small
> image where you can still read the class documentation in its raw form.
> In a minimalist image you might even strip down class comments to save
> space, so it's not an issue here. These three levels are the ones I see.
>
> For the markdown in method comments. This is something I think about
> since a while. There is still something like the first comment as
> separation to the rest. For doing a whole class documentation this
> could be a low hanging fruit as a convention to start. You can use
> microdown in method comments, too. And that's (again) because it reads
> well in raw format. After that we have to learn. Especially to
> understand that the AST and a document model are just two different
> form of trees that express something about the method. If we find a
> good way to interleave those trees and can have a rich text component
> that is rendered nicely with the code it encloses we are a big step
> nearer to explained code which reversed means executable documentation.
>
> Norbert
> >
> >
> > -----
> > Cheers,
> > Sean
> > --
> > Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html
> >
>
>
>
