Re: [Pharo-dev] Robust Functionality vs. Minimalism (was "Microdown ?")
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 : > > > > 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 > > > > >
Re: [Pharo-dev] Robust Functionality vs. Minimalism (was "Microdown ?")
Sean, > Am 01.08.2020 um 20:23 schrieb Sean P. DeNigris : > > 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 >
[Pharo-dev] Robust Functionality vs. Minimalism (was "Microdown ?")
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. - Cheers, Sean -- Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html
