From 287ad467b1cfb0fdcee5a54896df42e05480d982 Mon Sep 17 00:00:00 2001 From: Gabriel Darbord Date: Fri, 7 Jun 2024 00:29:14 +0200 Subject: [PATCH] Refresh class comments in Microdown package --- src/Microdown/ManifestMicrodown.class.st | 86 ++++++++----- .../MicAbsoluteResourceReference.class.st | 2 +- src/Microdown/MicAbstractBlock.class.st | 6 +- src/Microdown/MicAbstractCodeBlock.class.st | 2 +- src/Microdown/MicAnchorBlock.class.st | 6 +- src/Microdown/MicAnchorLinker.class.st | 9 +- .../MicAnchorReferenceBlock.class.st | 6 +- src/Microdown/MicAnnotatedBlock.class.st | 11 +- src/Microdown/MicAnnotationBlock.class.st | 6 +- src/Microdown/MicArgumentList.class.st | 26 ++-- src/Microdown/MicBlockQuoteBlock.class.st | 10 +- src/Microdown/MicCitationBlock.class.st | 5 +- src/Microdown/MicCodeBlock.class.st | 35 +++--- src/Microdown/MicColumnBlock.class.st | 5 +- src/Microdown/MicColumnsBlock.class.st | 10 +- src/Microdown/MicCommentBlock.class.st | 8 +- .../MicContinuousMarkedBlock.class.st | 16 +-- src/Microdown/MicEnvironmentBlock.class.st | 16 +-- src/Microdown/MicEvaluatedBlock.class.st | 2 +- src/Microdown/MicFigureBlock.class.st | 4 +- .../MicFileResourceReference.class.st | 18 +-- src/Microdown/MicFootnoteBlock.class.st | 2 +- .../MicHTTPResourceReference.class.st | 4 +- src/Microdown/MicHeaderBlock.class.st | 8 +- src/Microdown/MicHorizontalLineBlock.class.st | 2 +- src/Microdown/MicInlineBlockWithUrl.class.st | 2 +- src/Microdown/MicInlineElement.class.st | 8 +- src/Microdown/MicInlineHttpBlock.class.st | 4 +- src/Microdown/MicInputfileBlock.class.st | 5 +- src/Microdown/MicLinkBlock.class.st | 5 +- src/Microdown/MicListBlock.class.st | 7 +- src/Microdown/MicListItemBlock.class.st | 25 ++-- src/Microdown/MicMathBlock.class.st | 18 ++- src/Microdown/MicMathInlineBlock.class.st | 3 +- src/Microdown/MicMetaDataBlock.class.st | 2 +- .../MicMonospaceFormatBlock.class.st | 2 +- src/Microdown/MicOrderedListBlock.class.st | 11 +- src/Microdown/MicOutputStream.class.st | 2 +- src/Microdown/MicParagraphBlock.class.st | 2 +- src/Microdown/MicPharoEvaluatorBlock.class.st | 7 ++ .../MicPharoImageResourceReference.class.st | 8 +- src/Microdown/MicPharoScriptBlock.class.st | 6 +- src/Microdown/MicRawBlock.class.st | 5 +- .../MicRelativeResourceReference.class.st | 2 +- src/Microdown/MicResourceReference.class.st | 21 ++-- .../MicResourceReferenceError.class.st | 4 +- src/Microdown/MicRootBlock.class.st | 2 +- .../MicSameStartStopMarkupBlock.class.st | 15 ++- src/Microdown/MicScriptBlock.class.st | 8 +- src/Microdown/MicSingleLineBlock.class.st | 4 +- src/Microdown/MicSlideBlock.class.st | 4 +- src/Microdown/MicSourceBlock.class.st | 2 +- .../MicStartStopMarkupBlock.class.st | 2 +- src/Microdown/MicTableBlock.class.st | 18 ++- src/Microdown/MicTextBlock.class.st | 2 +- src/Microdown/MicUnEvaluatedBlock.class.st | 2 +- src/Microdown/MicUnknownResourceUri.class.st | 2 +- src/Microdown/MicUnorderedListBlock.class.st | 13 +- src/Microdown/MicZincPathResolver.class.st | 16 +-- src/Microdown/Microdown.class.st | 5 +- src/Microdown/MicrodownParser.class.st | 113 ++++++++++-------- src/Microdown/MicrodownVisitor.class.st | 7 +- 62 files changed, 338 insertions(+), 331 deletions(-) diff --git a/src/Microdown/ManifestMicrodown.class.st b/src/Microdown/ManifestMicrodown.class.st index e83f9f6d..ad555828 100644 --- a/src/Microdown/ManifestMicrodown.class.st +++ b/src/Microdown/ManifestMicrodown.class.st @@ -1,67 +1,87 @@ " -I define a parser and code model for MicroDown. +I define a parser and a code model for Microdown. Microdown is a smaller mardown than but mardown, but it is more extensible. It supports the default markdown features: -- Header +- Headers - Lists -- Paragraph -- Code with arguments: key=val&key2=val2 -- Quote -- Table +- Paragraphs +- Code blocks with arguments: key=val&key2=val2 +- Quotes +- Tables - Emphasis - Figures and links But also - Environment with arguments - Anchors -- Annotated paragraph -- Math with arguments -- and more intra block elements such as extensible markups, raw, math, and references. +- Annotated paragraphs +- Math blocks with arguments +- and more intra block elements such as extensible markup, raw, math, and references. ### In Pharo Image Syntax Essence in 2 seconds -```language=undefined +```language=text - #Header + #Header - ```language=Pharo&caption=Beautiful&label=Fig1 - code - ``` - > Boring quote block - > Don't use me! + ```language=Pharo&caption=Beautiful&label=Fig1 + code + ``` + > Boring quote block + > Don't use me! - [Pharo is cool](http://pharo.org) + [Pharo is cool](http://pharo.org) - - item 1 - 1. sub item 1 - 3. sub item 2 - - item 2 + - item 1 + 1. sub item 1 + 3. sub item 2 + - item 2 - `in text` but for pharo hyper links to class, method and package - `Point`, `Point class`, `Point>>#setX:setY:`, `#’Microdown-Tests’ (for packages) + `in text` but for pharo hyper links to class, method and package + `Point`, `Point class`, `Point>>#setX:setY:`, `#'Microdown-Tests'` (for packages) ``` +Produces: +#Header + +```language=Pharo&caption=Beautiful&label=Fig1 +code +``` +> Boring quote block +> Don't use me! + +[Pharo is cool](http://pharo.org) + +- item 1 + 1. sub item 1 + 3. sub item 2 +- item 2 + +`in text` but for pharo hyper links to class, method and package +`Point`, `Point class`, `Point>>#setX:setY:`, `#'Microdown-Tests'` (for packages) + +*** ### Implementation notes -I follow the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in appendix A. +I follow the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in the appendix. -In short, the strategy is that at any point in time, we might have a number of children of the root which are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open. +In short, the strategy is that at any point in time, we can have a number of children of the root that are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open. -When a new line is read we do the following: +When a new line is read, we do the following: 1. Check if the new line can be consumed by current. - - as part of this a child of current can be made which can consume the new line + - As part of this, a child of current can be made which can consume the new line. 2. If current cannot consume the new line, we close current, move current to its parent, and repeat 1. -3. The root node can consume anything, for instance by making new nodes for storing the new line. -4. The root node is not closed until input is exhausted +3. The root node can consume anything, for instance by making new nodes to store the new line. +4. The root node is not closed until input is exhausted. -The other packages in this repository are the extensions made to produce Pillar model. -Such packages should be moved in the future to other location (probably pillar itself). +The other packages in this repository are the extensions made to produce the Pillar model. +Such packages should be moved to another location in the future (probably pillar itself). -### Acknowledgments -I was implemented by S. Ducasse, L. Dargaud and G. Polito. It is based on the work on markdown parsing of K. Osterbye. +### Acknowledgements +I was implemented by S. Ducasse, L. Dargaud and G. Polito. It is based on the work on markdown parsing by K. Osterbye. " Class { #name : 'ManifestMicrodown', diff --git a/src/Microdown/MicAbsoluteResourceReference.class.st b/src/Microdown/MicAbsoluteResourceReference.class.st index fe7a9a11..327367c6 100644 --- a/src/Microdown/MicAbsoluteResourceReference.class.st +++ b/src/Microdown/MicAbsoluteResourceReference.class.st @@ -2,7 +2,7 @@ I represent a superclass for all absolute references. A reference will then be resolved and produces a resource. -Common for all absolute references is that they store their reference in a uri (ZnUrl). +Common to all absolute references is that they store their reference in a URI (`ZnUrl`). " Class { #name : 'MicAbsoluteResourceReference', diff --git a/src/Microdown/MicAbstractBlock.class.st b/src/Microdown/MicAbstractBlock.class.st index 3e2a3e2f..42642ece 100644 --- a/src/Microdown/MicAbstractBlock.class.st +++ b/src/Microdown/MicAbstractBlock.class.st @@ -1,10 +1,10 @@ " -I am the abstract node of the block objects generated by `MicroDownParser`. +I am the abstract node of the block objects generated by `MicrodownParser`. -The root of the parsetree is an instance of `MicRootBlock`. +The root of the parse tree is an instance of `MicRootBlock`. I have a set of children, and an uplink to my parent. -See the comment of `MicroDownParser` for an overview of the algorithm used in building such parse tree. +See the comment of `MicrodownParser` for an overview of the algorithm used to build such a parse tree. " Class { #name : 'MicAbstractBlock', diff --git a/src/Microdown/MicAbstractCodeBlock.class.st b/src/Microdown/MicAbstractCodeBlock.class.st index e18ef8f0..4313c8a6 100644 --- a/src/Microdown/MicAbstractCodeBlock.class.st +++ b/src/Microdown/MicAbstractCodeBlock.class.st @@ -1,5 +1,5 @@ " -I am common class for two extension blocks which at the moment shares the same syntax. +I am the common class for two extension blocks that currently share the same syntax. " Class { #name : 'MicAbstractCodeBlock', diff --git a/src/Microdown/MicAnchorBlock.class.st b/src/Microdown/MicAnchorBlock.class.st index 5d460f32..536541ee 100644 --- a/src/Microdown/MicAnchorBlock.class.st +++ b/src/Microdown/MicAnchorBlock.class.st @@ -1,10 +1,10 @@ " -I'm block that represents an anchor to a section. This way text can refer to the anchor to refer to the section. +I'm block that represents an anchor to a section. This way, text can refer to the anchor to refer to the section. -``` +```language=text # A section @mylovelySection -``` +``` " Class { #name : 'MicAnchorBlock', diff --git a/src/Microdown/MicAnchorLinker.class.st b/src/Microdown/MicAnchorLinker.class.st index f3a43f38..b84d89c6 100644 --- a/src/Microdown/MicAnchorLinker.class.st +++ b/src/Microdown/MicAnchorLinker.class.st @@ -1,14 +1,13 @@ " -I'm a vistor connecting anchors to their target. -For example in the following situation I will make sure that sec has the header as target. +I'm a vistor who connects anchors to their target. +For example, in the following situation, I will make sure that the `sec` label has the header as its target. -``` +```text # header @sec ``` -I'm usually invoked in a post parsing phase, so transparent to the user. - +I'm usually invoked in a post parsing phase, so it's transparent to the user. " Class { #name : 'MicAnchorLinker', diff --git a/src/Microdown/MicAnchorReferenceBlock.class.st b/src/Microdown/MicAnchorReferenceBlock.class.st index f1f7505f..4e774517 100644 --- a/src/Microdown/MicAnchorReferenceBlock.class.st +++ b/src/Microdown/MicAnchorReferenceBlock.class.st @@ -1,10 +1,10 @@ " -I represent a reference to a section, figure, environment. I follow the pattern `*@`, label, `@*` +I represent a reference to a section, figure, or environment. I follow the pattern `*@`, label, `@*`. -``` +For example: +```text See *@fig1@* ``` - " Class { #name : 'MicAnchorReferenceBlock', diff --git a/src/Microdown/MicAnnotatedBlock.class.st b/src/Microdown/MicAnnotatedBlock.class.st index 071afa12..ebe94428 100644 --- a/src/Microdown/MicAnnotatedBlock.class.st +++ b/src/Microdown/MicAnnotatedBlock.class.st @@ -1,15 +1,14 @@ " -I represent a paragraph with the title. My title can only contain a string while my body can contain formatted text. +I represent a paragraph with the title. My title can only contain a string and my body can contain formatted text. I'm created with `!!paragraph` (such as `@@note` `@@important` in Pillar). -!!note This is important so I used exclamatation mark. - -### Known limits. +!!note This is important so I used exclamation marks. + +### Known Limitations We should revisit the implementation because there is something unclear. -Currently we cannot add list for example inside a annotatedBlock. +For example, we cannot currently add lists inside an annotatedBlock. See [https://github.com/pillar-markup/MicroDown/issues/54](https://github.com/pillar-markup/MicroDown/issues/54) - " Class { #name : 'MicAnnotatedBlock', diff --git a/src/Microdown/MicAnnotationBlock.class.st b/src/Microdown/MicAnnotationBlock.class.st index f3dd9978..744baec3 100644 --- a/src/Microdown/MicAnnotationBlock.class.st +++ b/src/Microdown/MicAnnotationBlock.class.st @@ -1,14 +1,14 @@ " -I represent an annotation delimted by `{!` and `!}`: a tag with parameters. +I represent an annotation, a tag with parameters, delimited by `{!` and `!}`. -The following is a citation annotation with as parameters the name variable bound to the string 'Duca99a'. +The following example is a citation annotation with the name variable bound to the string 'Duca99a' as a parameter. ```text {!citation|name=Duca99a!} ``` ``` -MicroDownParser parse: '{!citation|name=Duca99a!}' +MicrodownParser parse: '{!citation|name=Duca99a!}' ``` " Class { diff --git a/src/Microdown/MicArgumentList.class.st b/src/Microdown/MicArgumentList.class.st index 7ce8c755..4a77faf5 100644 --- a/src/Microdown/MicArgumentList.class.st +++ b/src/Microdown/MicArgumentList.class.st @@ -1,30 +1,30 @@ " I am intended to provide arguments to annotations, codeblocks and environments. -I'm used in figures, code, and math equation for now +Currently, I'm used in figures, code, and math equation. -In the following anchor=fig1&width=70 is an argument list. -``` +In the following, `anchor=fig1&width=70` is an argument list. +```text ![this is a caption](figures/f.png anchor=fig1&width=70) ``` -``` - ```pharo - ... - ``` +```text + ```pharo + ... + ``` ``` -is equivalent to the set pharo as value to the default tag which is for blocks language +is equivalent to setting `pharo` as the value of the default tag, which for blocks is the language tag. -``` - ```language=pharo - ... - ``` +```text + ```language=pharo + ... + ``` ``` My syntax is of the following form: - ` ` defaultArg->initialValue, no other arguments. -- `value` defaultArg->value, no otherarguments. +- `value` defaultArg->value, no other arguments. - `key=arg[&key=arg]*`, defaultArg->initialValue, but arguments. - `value|key=arg[&key=arg]*` defaultArg->value, and arguments. " diff --git a/src/Microdown/MicBlockQuoteBlock.class.st b/src/Microdown/MicBlockQuoteBlock.class.st index 19eb1284..b9d41f6e 100644 --- a/src/Microdown/MicBlockQuoteBlock.class.st +++ b/src/Microdown/MicBlockQuoteBlock.class.st @@ -1,14 +1,12 @@ " -I represent preformatted paragraph indicated by '> ' at the beginning of each my lines. +I represent a preformatted paragraph indicated by '> ' at the beginning of each of my lines. I'm like a preformatted in HTML or Pillar '= '. -Every single line should starts with '> '. +Every single line should start with '> '. -The semantics of microdown quote block is that blocks (code block, header, lists) are not interpreted inside only formatting. +The semantics of Microdown quote block is that blocks (code blocks, headers, lists) are not interpreted inside only formatting. -In githubmarkdown the definitions are just super complex and we do not follow them. +In GitHub Markdown, the definitions are really complex and we do not follow them. ""A block quote marker consists of 0-3 spaces of initial indent, plus (a) the character > together with a following space, or (b) a single character > not followed by a space."" - - " Class { #name : 'MicBlockQuoteBlock', diff --git a/src/Microdown/MicCitationBlock.class.st b/src/Microdown/MicCitationBlock.class.st index e17e9fb3..8322dd43 100644 --- a/src/Microdown/MicCitationBlock.class.st +++ b/src/Microdown/MicCitationBlock.class.st @@ -1,11 +1,10 @@ " -A citation is an inline element that represents a bibliography reference as in LaTeX for example. +A citation is an inline element that represents a bibliography reference, such as in LaTeX. The bibliography will be able to extract its entries from the reference in the citation. -``` +```language=text this is a text with a {!citation|ref=Duca99a!} ``` - " Class { #name : 'MicCitationBlock', diff --git a/src/Microdown/MicCodeBlock.class.st b/src/Microdown/MicCodeBlock.class.st index 8cd0fb23..5d4210d6 100644 --- a/src/Microdown/MicCodeBlock.class.st +++ b/src/Microdown/MicCodeBlock.class.st @@ -1,29 +1,28 @@ " -I am a code block. I look like this, starting and ending with three $` -my 'arguments' is just the text from the fourth character up to the end of line. +I am a code block. I look like this, starting and ending with three `$`` (backticks). +My 'arguments' variable is the text starting from the fourth character to the end of the line. -``` - \`\`\`arguments +```text + ```arguments line 1 line 2 line 3 - \`\`\` + ``` ``` -A codeblock does not interpreter its contents. -You can however specify different tags such as an anchor and a caption. +A codeblock does not interpret its contents. +However, you can specify different tags, such as an anchor and a caption. -``` - ```language=pharo|caption=A method&anchor=method - pharoMotto - ^ 'Doing something every is the best way to make progress' - ``` +```text + ```language=pharo|caption=A method&anchor=method + pharoMotto + ^ 'Doing something every day is the best way to make progress' + ``` ``` +For now we do not support the use of multiple backticks. The markup is only 3 backticks. If you want to nest codeblocks within codeblocks, you must use an extra space. -For now we do not support the use of multiple backticks. The markup is only 3 backticks. If you want to embed codeblock inside codeblock you must use an extra space. - -``` +```text ``` ``` A nested codeblock @@ -31,9 +30,9 @@ For now we do not support the use of multiple backticks. The markup is only 3 ba ``` ``` -#### Implementation thoughts -The current implementation stores lines in a single text and this is a bad idea because first what if the user use lf in his text! -Second if we want to treat lines separatedly we have to reparse it. Now we do not need it so this is good but this is just by chance! +#### Implementation Thoughts +The current implementation stores lines in a single text and this is a bad idea because first what if the user uses `lf`/`cr` in his text! +Second if we want to treat lines separately, we have to reparse them. Now we do not need it so this is good but this is just by chance! " Class { #name : 'MicCodeBlock', diff --git a/src/Microdown/MicColumnBlock.class.st b/src/Microdown/MicColumnBlock.class.st index 364d87fc..d9900617 100644 --- a/src/Microdown/MicColumnBlock.class.st +++ b/src/Microdown/MicColumnBlock.class.st @@ -1,10 +1,9 @@ " -I'm a bloc element that represents a column. I have one optional argument that is the width of the column. I should be nested in a ColumnsBlock element. +I'm a block element that represents a column. I have one optional argument that is the width of the column. I should be nested in a ColumnsBlock element. -``` +```language=text diff --git a/src/Microdown/MicColumnsBlock.class.st b/src/Microdown/MicColumnsBlock.class.st index dde952fd..09431ef8 100644 --- a/src/Microdown/MicColumnsBlock.class.st +++ b/src/Microdown/MicColumnsBlock.class.st @@ -1,17 +1,14 @@ " To support multiple columns in document. -``` +```language=text @@ -20,12 +17,9 @@ To support multiple columns in document. Note that a column can have also a width. - -``` +```language=text diff --git a/src/Microdown/MicCommentBlock.class.st b/src/Microdown/MicCommentBlock.class.st index 7f051091..b3284b31 100644 --- a/src/Microdown/MicCommentBlock.class.st +++ b/src/Microdown/MicCommentBlock.class.st @@ -1,9 +1,9 @@ " -A commented line in Pillar is a line starting with %. -A comment does not flow on multiple lines. -Each line to be commented should start with %. +A commented line in Pillar is a line that starts with %. +A comment does not run across multiple lines. +Each commented line should start with %. -I should be a subclass of SingleLineBlock and not continuousMarkedBlock. +I should be a subclass of `MicSingleLineBlock`, not `MicContinuousMarkedBlock`. " Class { #name : 'MicCommentBlock', diff --git a/src/Microdown/MicContinuousMarkedBlock.class.st b/src/Microdown/MicContinuousMarkedBlock.class.st index 15259e33..d82f20f1 100644 --- a/src/Microdown/MicContinuousMarkedBlock.class.st +++ b/src/Microdown/MicContinuousMarkedBlock.class.st @@ -1,33 +1,29 @@ " -I'm an abstract block for blocks requiring a systematic simple character or character sequences at the beginning of each line. The text of the lines are accumulated for now as line without the markup separated by a newline. +I'm an abstract block for blocks that require a systematic single character or character sequences at the beginning of each line. The text of the lines is initially collected without markup, separated by a newline. For example -``` +```language=text % comment 1 % comment 2 ``` produces a single comment object with text as follows: -``` +```language=text comment 1 comment 2 ``` For example -``` +```language=text > this is an example > and another one ``` - -produces +produces: > this is an example > and another one - - - - + " Class { #name : 'MicContinuousMarkedBlock', diff --git a/src/Microdown/MicEnvironmentBlock.class.st b/src/Microdown/MicEnvironmentBlock.class.st index ca98bb59..3252bfc4 100644 --- a/src/Microdown/MicEnvironmentBlock.class.st +++ b/src/Microdown/MicEnvironmentBlock.class.st @@ -1,10 +1,13 @@ " -An environment is delimited by a start and end markup and it can have an argument list. -By default I do not handle any form of formatting in the potential arguments. +An environment is delimited by a start and end markup, and it can have an argument list. +By default, I do not handle any form of formatting in the arguments. ## Syntax +% Examples do not work (as of 06/23), it would be nice to show one. + ```text + @@ -13,14 +16,13 @@ Here is an example of a slide (subclass of `MicEnvironmentBlock`) ```text ``` -This is important to support better column in the future: +This is important for better column support in the future: ```text @@ -34,13 +36,11 @@ This is important to support better column in the future: -- press the button ==class== to define a class method +- press the ==class== button to define a class method - in lectures, we add ==class== !> !> ``` - - " Class { #name : 'MicEnvironmentBlock', diff --git a/src/Microdown/MicEvaluatedBlock.class.st b/src/Microdown/MicEvaluatedBlock.class.st index c077c64f..1e7ac0d6 100644 --- a/src/Microdown/MicEvaluatedBlock.class.st +++ b/src/Microdown/MicEvaluatedBlock.class.st @@ -1,5 +1,5 @@ " -I represent in paragraph element with substructures. Typically text formatting such as italics inside bold. +I represent in paragraph element with substructures. Typically, text formatting such as italics and bold. " Class { #name : 'MicEvaluatedBlock', diff --git a/src/Microdown/MicFigureBlock.class.st b/src/Microdown/MicFigureBlock.class.st index ba61c0c9..fbd11a8a 100644 --- a/src/Microdown/MicFigureBlock.class.st +++ b/src/Microdown/MicFigureBlock.class.st @@ -6,9 +6,9 @@ My syntax is: `![Here is a nice caption.](https://files.pharo.org/media/logo/log You should get the following picture: ![Here is a nice caption.](https://files.pharo.org/media/logo/logo.png ""anchor=figanchor&width=80"") -I have a resources, i.e. an object referencing either a file (in relative or absolute manner) or an Url, that refers to a given image object. +I have a resource, i.e. an object referencing either a file (in relative or absolute manner), or an URL that refers to a given image object. -What is important to see is that there is a space between the url arguments and microdown arguments. +What is important to see is that there is a space between the URL argument and microdown arguments. " Class { #name : 'MicFigureBlock', diff --git a/src/Microdown/MicFileResourceReference.class.st b/src/Microdown/MicFileResourceReference.class.st index 35b44f03..8dc98c9c 100644 --- a/src/Microdown/MicFileResourceReference.class.st +++ b/src/Microdown/MicFileResourceReference.class.st @@ -1,20 +1,20 @@ " -I am a file reference encapsulating a file uri (`file:/path/to/some/file.md`). +I am a file reference encapsulating a file URI (`file:/path/to/some/file.md`). -## Ambiguity of uri -Inside the pharo image, string based file references are ambiguous. `/path/to/some/file.md` might mean a file on disk, or a file in the memory file system. +## Ambiguity of URI +Inside the pharo image, string-based file references are ambiguous. `/path/to/some/file.md` could mean a file on disk, or a file in the memory file system. -I will assume disk based if not told otherwise. +I will assume it is disk-based unless told otherwise. -I can however, be given an explisit filesystem for disambigutation using method `filesystem:`. +However, I can be given an explicit filesystem for disambiguation using the `filesystem:` method. -## Creation from pharo FileReference -Normally instances of `MicResourceReference` are created using `MicResourceReference fromUri: uriString`. +## Creation from Pharo FileReference +Normally, instances of `MicResourceReference` are created using `MicResourceReference fromUri: uriString`. -You can get an instance of me from a pharo `FileReference` using `MicFileResourceReference fromFileRef: aFileRef`. The filesystem of `aFileRef` is taken into account. +You can get an instance of me from a Pharo `FileReference` using `MicFileResourceReference fromFileRef: aFileRef`. The filesystem of `aFileRef` is taken into account. ## Examples -The test class `MicFileResourceTest` has two tests `testLoadImage` and `testLoadMicrodown` which show how to use me. +The test class `MicFileResourceReferenceTest` has two tests `testLoadImage` and `testLoadMicrodown` that show how to use me. " Class { #name : 'MicFileResourceReference', diff --git a/src/Microdown/MicFootnoteBlock.class.st b/src/Microdown/MicFootnoteBlock.class.st index 77d9ba96..f64f288d 100644 --- a/src/Microdown/MicFootnoteBlock.class.st +++ b/src/Microdown/MicFootnoteBlock.class.st @@ -1,7 +1,7 @@ " I'm an inline element that represents a footnote as in LaTeX for example. The bibliography will be able to extract its entries from the reference in the citation. -this is a text with a `{!footnote|note=Here is a nice footenote.!}` +this is a text with a `{!footnote|note=Here is a nice footenote.!}`. {!footnote|note=Here is a nice footenote.!} " Class { #name : 'MicFootnoteBlock', diff --git a/src/Microdown/MicHTTPResourceReference.class.st b/src/Microdown/MicHTTPResourceReference.class.st index c53383bc..6186cb77 100644 --- a/src/Microdown/MicHTTPResourceReference.class.st +++ b/src/Microdown/MicHTTPResourceReference.class.st @@ -1,7 +1,5 @@ " -I am a http reference encapsulating a http uri (`http//host/path/to/some/file.md`). - - +I am a HTTP reference encapsulating a HTTP URI (`http://host/path/to/some/file.md`). " Class { #name : 'MicHTTPResourceReference', diff --git a/src/Microdown/MicHeaderBlock.class.st b/src/Microdown/MicHeaderBlock.class.st index f9f45ca0..a9d1b590 100644 --- a/src/Microdown/MicHeaderBlock.class.st +++ b/src/Microdown/MicHeaderBlock.class.st @@ -1,9 +1,9 @@ " -I am a header. I'm composed of a number of sharp sign (1 to 6) followed by a space (obligatory) and a text on one line. +I am a header. I'm composed of a number of sharp characters (1 to 6) followed by a space (mandatory) and a text on one line. For example -``` +```language=text # level 1 ## level 2 ### level 3 @@ -12,7 +12,7 @@ For example ###### level 6 ``` -produces +Produces: # level 1 ## level 2 @@ -20,7 +20,7 @@ produces #### level 4 ##### level 5 ###### level 6 - + " Class { #name : 'MicHeaderBlock', diff --git a/src/Microdown/MicHorizontalLineBlock.class.st b/src/Microdown/MicHorizontalLineBlock.class.st index 77b54353..ad9fab0d 100644 --- a/src/Microdown/MicHorizontalLineBlock.class.st +++ b/src/Microdown/MicHorizontalLineBlock.class.st @@ -1,5 +1,5 @@ " -I'm an horizontal line. I'm expressed by using a new line with `***` +I am a horizontal line. I'm expressed by starting a new line with `***` *** the rest of the line is ignored. " diff --git a/src/Microdown/MicInlineBlockWithUrl.class.st b/src/Microdown/MicInlineBlockWithUrl.class.st index e3af821a..24180f67 100644 --- a/src/Microdown/MicInlineBlockWithUrl.class.st +++ b/src/Microdown/MicInlineBlockWithUrl.class.st @@ -1,7 +1,7 @@ " My subclasses manage figures and links. -``` +```text ![Pharologo](https://files.pharo.org/media/logo/logo.png ``` diff --git a/src/Microdown/MicInlineElement.class.st b/src/Microdown/MicInlineElement.class.st index 0ab61a50..dd7020e6 100644 --- a/src/Microdown/MicInlineElement.class.st +++ b/src/Microdown/MicInlineElement.class.st @@ -3,11 +3,9 @@ I am an inline block generated by inline splitter, to parse inline text. I am characterized by: - start & end: locations of my opener & closer delimiters in initial string -- substring: concerned text (without delimiters so) -- kind: my type, symbol which must be the same than my relative delimiter type (#basic for normal text) -- children: array in case of nested inline blocks - - +- substring: concerned text (without delimiters) +- kind: my type, symbol which must be the same as my relative delimiter type (#basic for normal text) +- children: array in case of nested inline block " Class { #name : 'MicInlineElement', diff --git a/src/Microdown/MicInlineHttpBlock.class.st b/src/Microdown/MicInlineHttpBlock.class.st index 1c530629..728f827a 100644 --- a/src/Microdown/MicInlineHttpBlock.class.st +++ b/src/Microdown/MicInlineHttpBlock.class.st @@ -1,6 +1,6 @@ " -I implement the inline use of `https://somewhere.com` as a link directly in microdown. -My parse method on the class side transform me directly into a MicLinkBlock, and as such, I am never instantiated +I implement the inline use of `https://somewhere.com` as a link directly in Microdown. +My parse method on the class side turns me directly into a `MicLinkBlock`, and as such, I am never instantiated. " Class { #name : 'MicInlineHttpBlock', diff --git a/src/Microdown/MicInputfileBlock.class.st b/src/Microdown/MicInputfileBlock.class.st index ae9f5e93..c945f800 100644 --- a/src/Microdown/MicInputfileBlock.class.st +++ b/src/Microdown/MicInputfileBlock.class.st @@ -1,6 +1,6 @@ " -I handle input file. -Note that I should start a new line but I can end on the same line. So I may look like an inline element but I'm a block one. +I handle an input file. +Note that I should start on a new line but I can end on the same line. So I may look like an inline element but I'm a block one. ```text @@ -14,6 +14,7 @@ Example: Gives: +*** " Class { #name : 'MicInputfileBlock', diff --git a/src/Microdown/MicLinkBlock.class.st b/src/Microdown/MicLinkBlock.class.st index 3de7d3a9..bd66498b 100644 --- a/src/Microdown/MicLinkBlock.class.st +++ b/src/Microdown/MicLinkBlock.class.st @@ -1,7 +1,6 @@ " -I represent a reference in a text. For example `[The pharo web site](http://pharo.org)` creates [The Pharo web site](http://pharo.org). - -- The reference message returns the `http://pharo.org` part +I represent a reference in a text. For example, `[The pharo web site](http://pharo.org)` gives [The Pharo web site](http://pharo.org). +The `reference` method returns the `http://pharo.org` part. " Class { #name : 'MicLinkBlock', diff --git a/src/Microdown/MicListBlock.class.st b/src/Microdown/MicListBlock.class.st index edfa8ff2..ece0d60a 100644 --- a/src/Microdown/MicListBlock.class.st +++ b/src/Microdown/MicListBlock.class.st @@ -1,6 +1,6 @@ " I am an abstract class for the two kind of lists, ordered and unordered. -When I created I automatically add a listitem as my child. +When I am created, I automatically add a listitem as my child. Unordered list line starts with `-`, ordered list starts with number. An empty or a wrong indent closes me. @@ -13,7 +13,7 @@ Here is an example: Indentation (two spaces) matters and is crucial. Here is an example -``` +```language=text - item 1 xx- subitem 1.1 xx- subitem 2.1 @@ -22,7 +22,7 @@ xx- subitem 2.1 xxxx- subsubitem 2.1.1 xx- subitem 2.2 ``` -produces: +Produces: - item 1 - subitem 1.1 - subitem 2.1 @@ -39,7 +39,6 @@ Now an ordered list can also contain an unordered list. 3. third - " Class { #name : 'MicListBlock', diff --git a/src/Microdown/MicListItemBlock.class.st b/src/Microdown/MicListItemBlock.class.st index 80d2cd13..85c395b5 100644 --- a/src/Microdown/MicListItemBlock.class.st +++ b/src/Microdown/MicListItemBlock.class.st @@ -1,30 +1,30 @@ " -I represent one item in a list (ordered or non-ordered). +I represent an item in a list (ordered or unordered). -``` +```language=text 1. item 1 2. item 2 ``` -or -``` +or +```language=text - item 1 - item 2 ``` -are two lists containing 2 item list elements. +are two lists containing 2 list items. -An item list can be on multiple lines +A list item can be on multiple lines: -``` +```language=text 1. item 1 **foo** on the same item element 2. is another element -3. and a third one on - another line +3. and a third one on + another line ``` -Please note that I can contain nested subelements and +Please note that I can contain nested sub-elements: -``` +```language=text 1. item 1 **foo** on the same item - sublevel item 1 **bold** @@ -35,9 +35,8 @@ Please note that I can contain nested subelements and Therefore I expose two APIs: - `children` which returns all the mic elements (for example the text and the nested lists) - `textElements` which returns only the text elements (for example `item 1 **foo** on the same item`) - -Pay attention my instance variable text is only used during the parsing time. +Pay attention that my instance variable `text` is only used during parsing. " Class { #name : 'MicListItemBlock', diff --git a/src/Microdown/MicMathBlock.class.st b/src/Microdown/MicMathBlock.class.st index 50fc57c3..801d4c4e 100644 --- a/src/Microdown/MicMathBlock.class.st +++ b/src/Microdown/MicMathBlock.class.st @@ -1,35 +1,33 @@ " -I'm a math environment. I'm a block it means that I start by a newline with character `$$` and optional parameters, and I finish by a line with the same characters. -My body can be on multiple line and may contain LaTeX expressions. -In particular it means that my body does not contain nested elements. +I'm a math environment. I'm a block, which means that I start on a new line with the `$$` markup, take optional parameters, and end on a new line with the same markup. +My body can be on multiple lines and can contain LaTeX expressions. +In particular, this means that my body does not contain nested elements. Here is an example -``` +```text $$ V_i = C_0 - C_3 $$ ``` -produces +Produces: $$ V_i = C_0 - C_3 $$ - -Now if you want to have label and references to an equation as in LaTeX you should prefix the parameter with % (else it will break on github). + +If you want to have a label and references to an equation as in LaTeX, you should prefix the parameter with `%` (otherwise it breaks on GitHub). -``` +```text $$ % label=theEq V_i = C_0 - C_3 $$ See *@theEq@* ``` - - " Class { #name : 'MicMathBlock', diff --git a/src/Microdown/MicMathInlineBlock.class.st b/src/Microdown/MicMathInlineBlock.class.st index fe51c962..f98653ae 100644 --- a/src/Microdown/MicMathInlineBlock.class.st +++ b/src/Microdown/MicMathInlineBlock.class.st @@ -1,5 +1,5 @@ " -Microdown supports in text math expression as in LaTeX using `$ 1 + 2 $`. Each exporter is then responsible to map the contents to the correct output. For PDF based on LaTeX mathInlineBlock can contain LaTeX, for HTML we expect the same using corresponding math library in JS. +Microdown supports mathematical expressions in text as in LaTeX, e.g. `$ 1 + 2 $`. Each exporter is then responsible for mapping the content to the correct output. For PDF based on LaTeX, `mathInlineBlock` can contain LaTeX. For HTML, we expect the same using the corresponding math library in JS. Here are several examples: @@ -22,7 +22,6 @@ $\sin(x) = \sum_{n=0}^{\infty} \frac{(-1)^{n}x^{2n+1}}{(2n+1)!}$ Code: `$f(a) = \frac{1}{2\pi i} \oint_{\gamma} \frac{f(z)}{z - a} dz$` $f(a) = \frac{1}{2\pi i} \oint_{\gamma} \frac{f(z)}{z - a} dz$ - " Class { #name : 'MicMathInlineBlock', diff --git a/src/Microdown/MicMetaDataBlock.class.st b/src/Microdown/MicMetaDataBlock.class.st index 8acbccca..118db39b 100644 --- a/src/Microdown/MicMetaDataBlock.class.st +++ b/src/Microdown/MicMetaDataBlock.class.st @@ -4,7 +4,7 @@ We will have to learn from doing the migration. In Microdown, metadata is a block level expressed as follows: -``` +```language=text { ""title"": ""Selecting Expressions"", ""author"": ""S. Ducasse and L. Fabresse with Q. Ducasse"", diff --git a/src/Microdown/MicMonospaceFormatBlock.class.st b/src/Microdown/MicMonospaceFormatBlock.class.st index 1ebd39c4..b0b6346c 100644 --- a/src/Microdown/MicMonospaceFormatBlock.class.st +++ b/src/Microdown/MicMonospaceFormatBlock.class.st @@ -1,5 +1,5 @@ " -I represent a monospaced text section. I'm delimited using `\`` as in `\`monospace\`` to obtain `monospace`. +I represent a monospaced text section. I'm delimited using `\`` (backtick) as in `\`monospace\`` to obtain `monospace`. " Class { #name : 'MicMonospaceFormatBlock', diff --git a/src/Microdown/MicOrderedListBlock.class.st b/src/Microdown/MicOrderedListBlock.class.st index b263fbb5..1ad7d680 100644 --- a/src/Microdown/MicOrderedListBlock.class.st +++ b/src/Microdown/MicOrderedListBlock.class.st @@ -4,25 +4,24 @@ I represent an ordered list of list items. #### Example Typing -``` +```language=text 1. first 2. second - on multiple line + on multiple lines 1. third Not in third 1. first item of a new list ``` -produces +Produces: 1. first 1. second - on multiple line + on multiple lines 1. third Not in third 1. first item of a new list -Notice how the following line of the second item is indented with the previous one. - +Notice how the second line of the second item is indented like the first line. " Class { #name : 'MicOrderedListBlock', diff --git a/src/Microdown/MicOutputStream.class.st b/src/Microdown/MicOutputStream.class.st index 8440cb95..bcb5b14f 100644 --- a/src/Microdown/MicOutputStream.class.st +++ b/src/Microdown/MicOutputStream.class.st @@ -1,5 +1,5 @@ " -I'm a little wrapper on stream to provide a nicer API. In particular I help not hardcoding line ending everywhere. +I'm a little wrapper on stream to provide a nicer API. In particular, I help avoid hardcoding line endings everywhere. " Class { #name : 'MicOutputStream', diff --git a/src/Microdown/MicParagraphBlock.class.st b/src/Microdown/MicParagraphBlock.class.st index 8eafc7f3..3dea057f 100644 --- a/src/Microdown/MicParagraphBlock.class.st +++ b/src/Microdown/MicParagraphBlock.class.st @@ -1,7 +1,7 @@ " I am a plain text paragraph. -If am divided from other paragraphs by either a blank line, or one of the other markups. +I am divided from other paragraphs by either a blank line, or one of the other markups. " Class { #name : 'MicParagraphBlock', diff --git a/src/Microdown/MicPharoEvaluatorBlock.class.st b/src/Microdown/MicPharoEvaluatorBlock.class.st index 3b901a29..ccac9831 100644 --- a/src/Microdown/MicPharoEvaluatorBlock.class.st +++ b/src/Microdown/MicPharoEvaluatorBlock.class.st @@ -2,9 +2,16 @@ I am a block containing a Pharo expression. A script showing my visitors: +```language=text + ```pharoeval + Transcript show: 'Test'; cr. + ``` +``` +Gives: ```pharoeval Transcript show: 'Test'; cr. ``` + " Class { #name : 'MicPharoEvaluatorBlock', diff --git a/src/Microdown/MicPharoImageResourceReference.class.st b/src/Microdown/MicPharoImageResourceReference.class.st index 89a2c899..f478e5e4 100644 --- a/src/Microdown/MicPharoImageResourceReference.class.st +++ b/src/Microdown/MicPharoImageResourceReference.class.st @@ -1,15 +1,15 @@ " -I am a reference to a image or microdown ressource in the image. +I am a reference to an image or microdown resource in the Pharo image. -I follow the url scheme `pharo:/class/selector/arg1/arg2`. My intended usage is to give access to the many icons in pharo using: `pharo:///Object/iconNamed:/nameOfIcon`. +I follow the URI scheme `pharo:///class/selector/arg1/arg2`. My intended use is to give access to the many icons in pharo using: `pharo:///Object/iconNamed:/nameOfIcon`. Examples: - abstract: ![](pharo:///Object/iconNamed:/abstract) - bitbucket: ![](pharo:///Object/iconNamed:/bitbucket) - thumbsUp: ![](pharo:///Object/iconNamed:/thumbsUp) -## Restictions -- Only class side methods can be invoked +## Restrictions +- Only class methods can be invoked - Only string arguments can be passed " Class { diff --git a/src/Microdown/MicPharoScriptBlock.class.st b/src/Microdown/MicPharoScriptBlock.class.st index 8ecc87a4..cc678366 100644 --- a/src/Microdown/MicPharoScriptBlock.class.st +++ b/src/Microdown/MicPharoScriptBlock.class.st @@ -10,12 +10,12 @@ A script showing my visitors: do: [:class | aBuilder item: [ aBuilder monospace: (class name, '>>#visitScript:') ]]]]) contents ``` - -or generating a morph - + +Or generating a morph: ```pharoscript|width=100&show=both Morph new ``` + " Class { #name : 'MicPharoScriptBlock', diff --git a/src/Microdown/MicRawBlock.class.st b/src/Microdown/MicRawBlock.class.st index 9098107d..58566d5a 100644 --- a/src/Microdown/MicRawBlock.class.st +++ b/src/Microdown/MicRawBlock.class.st @@ -1,8 +1,9 @@ " Raw lets the user place anything (so don't use it). -``` -{{ raw contents}} +Example: +```text +{{ raw contents }} ``` " Class { diff --git a/src/Microdown/MicRelativeResourceReference.class.st b/src/Microdown/MicRelativeResourceReference.class.st index 45c835be..9024b735 100644 --- a/src/Microdown/MicRelativeResourceReference.class.st +++ b/src/Microdown/MicRelativeResourceReference.class.st @@ -1,7 +1,7 @@ " I am a relative reference. -I specify a ressource relative to an other reference. One example is the path `../images/logo.png` which says the logo is in the image direcctory of my parent directory. However, I am unresolved, and need to be resolved with respect to an absolute reference (file or http). +I specify a resource relative to another reference. One example is the path `../images/logo.png`, which says the logo is in the images directory of my parent directory. However, I am unresolved and need to be resolved with respect to an absolute reference (file or http). " Class { #name : 'MicRelativeResourceReference', diff --git a/src/Microdown/MicResourceReference.class.st b/src/Microdown/MicResourceReference.class.st index 34201ed3..8cf23678 100644 --- a/src/Microdown/MicResourceReference.class.st +++ b/src/Microdown/MicResourceReference.class.st @@ -1,29 +1,26 @@ " -I represent a reference to binary or textual ressources, primarily images and microdown text. +I represent a reference to binary or textual resources, primarily images and Microdown text. -References occour in microdown in three different constructs: +References occur in Microdown in three different constructs: - external links - figures -- inputfiles +- input files -I have subclasses to give access to files and http bases resources, as well as access to resources already in the image. +I have subclasses to give access to files and http based resources, as well as access to resources already in the image. ## URI -Resources are primarily referenced using **Uniform Resource Identifiers** (uri), and are created by my class side method `fromUri:` - for example: `MicResourceReference fromUri: 'file:/path/to/mydocument.md'` or `MicResourceReference fromUri: 'https://host/path/to/myimage.png'` +Resources are primarily referenced using **Uniform Resource Identifiers** (URI), and are created by my class method `fromUri:`, for example: `MicResourceReference fromUri: 'file:/path/to/mydocument.md'` or `MicResourceReference fromUri: 'https://host/path/to/myimage.png'` ## Special cases As a special case `MicFileResourceReference` can be created from a regular pharo `FileReference`. -Besides the absolute resource references (file, http), `MicRelativeResourceReference` is a partial/relative reference, which must be resolved with respect to an absolute reference before the resource can be accessed. Resolution of relative references is done by `MicZincPathResolver`. +Besides the absolute resource references (file, http), `MicRelativeResourceReference` is a partial/relative reference, that must be resolved with respect to an absolute reference before the resource can be accessed. Resolution of relative references is done by `MicZincPathResolver`. ## Extension -It is possible to add new kinds of ResourceReferences. The idea is each ressource reference type uses its own schema name in the uri - for example files are supported by the scheme `file://....`. Your new resource reference should: - -- implement `handlesUriScheme:` on the class side returning true if the passes scheme is handled by your extension -- maybe override `newFromUri:` on the class side if your reference type need to handle the instantiation of reference objects - - +It is possible to add new kinds of ResourceReferences. The idea is that each resource reference type uses its own schema name in the URI. For example, files are supported by the scheme `file://...`. Your new resource reference should: +- implement `handlesUriScheme:` on the class side, returning true if the given scheme is handled by your extension. +- maybe override `newFromUri:` on the class side if your reference type needs to handle the instantiation of reference objects. " Class { #name : 'MicResourceReference', diff --git a/src/Microdown/MicResourceReferenceError.class.st b/src/Microdown/MicResourceReferenceError.class.st index 688bdb98..1467bece 100644 --- a/src/Microdown/MicResourceReferenceError.class.st +++ b/src/Microdown/MicResourceReferenceError.class.st @@ -1,6 +1,6 @@ " -Sometimes resources can not be accessed, their uri can be misspelled, the http server can be down, etc. -I am signalled when one tries to access a resource which can not be accessed for any reason. +Sometimes resources cannot be accessed, their URI can be misspelled, the http server can be down, etc. +I am signalled when one tries to access a resource that cannot be accessed for any reason. In particular, the methods `loadImage` and `loadMicrodown` in (subclasses of) `MicAbsoluteResourceReference` can signal me. " diff --git a/src/Microdown/MicRootBlock.class.st b/src/Microdown/MicRootBlock.class.st index bdf4fcd9..aa9dcd76 100644 --- a/src/Microdown/MicRootBlock.class.st +++ b/src/Microdown/MicRootBlock.class.st @@ -1,5 +1,5 @@ " -I am the root of the github markup tree +I am the root of the markup tree. " Class { #name : 'MicRootBlock', diff --git a/src/Microdown/MicSameStartStopMarkupBlock.class.st b/src/Microdown/MicSameStartStopMarkupBlock.class.st index 728d92b0..22ecf24c 100644 --- a/src/Microdown/MicSameStartStopMarkupBlock.class.st +++ b/src/Microdown/MicSameStartStopMarkupBlock.class.st @@ -1,11 +1,16 @@ " -I'm abstract block for the logic of elements which are managed by a +I'm an abstract block for the logic of elements which are managed by an identical start and stop markup. It can take a list of arguments. -startMarkup -body -endMarkup +For example: +```text + ```language=text + carpe diem + % verbatim + ``` +``` +defines a block that uses the same start and end markup, with the 'text' language argument. -My subclass should define lineMarkup +My subclasses should define `lineStartMarkup`, which is also used as the `lineStopMarkup`. " Class { #name : 'MicSameStartStopMarkupBlock', diff --git a/src/Microdown/MicScriptBlock.class.st b/src/Microdown/MicScriptBlock.class.st index c8a68222..f8ef6ad0 100644 --- a/src/Microdown/MicScriptBlock.class.st +++ b/src/Microdown/MicScriptBlock.class.st @@ -1,10 +1,10 @@ " I am a common superclass for script extensions. -A script extension is intened to have its body text interpreted. +A script extension is intended to have its body text interpreted. -A script extension should -- either be handled by the visitor, overriding the accept: method -- or building a microdown tree at parse time using closeMe +A script extension should **either**: +- be handled by the visitor by overriding the `accept:` method +- build a Microdown tree at parse time using `closeMe` " Class { #name : 'MicScriptBlock', diff --git a/src/Microdown/MicSingleLineBlock.class.st b/src/Microdown/MicSingleLineBlock.class.st index 3c6021b1..17f5252c 100644 --- a/src/Microdown/MicSingleLineBlock.class.st +++ b/src/Microdown/MicSingleLineBlock.class.st @@ -1,6 +1,6 @@ " -I characterize one liners. -They do not know consumeLine: beacuse they are composed of only one line. +I characterize one-liners. +They do not know `consumeLine:` beacuse they are composed of only one line. " Class { #name : 'MicSingleLineBlock', diff --git a/src/Microdown/MicSlideBlock.class.st b/src/Microdown/MicSlideBlock.class.st index 24570f0b..f202ec0c 100644 --- a/src/Microdown/MicSlideBlock.class.st +++ b/src/Microdown/MicSlideBlock.class.st @@ -2,7 +2,7 @@ I'm a block element defining a slide. I expect a title and optionally a tag (to be able for example to have the same slide but on two different layouts and not emit both. -``` +```language=text ``` - -It should be noted that the title is not reified as a Microdown object because so far the extensions does not support a way to describe the argument that should be reified. " Class { #name : 'MicSlideBlock', diff --git a/src/Microdown/MicSourceBlock.class.st b/src/Microdown/MicSourceBlock.class.st index 47533997..e82fee86 100644 --- a/src/Microdown/MicSourceBlock.class.st +++ b/src/Microdown/MicSourceBlock.class.st @@ -6,7 +6,7 @@ I am an extension for including source code into markdown document. I am to be u Yielding: -The `side` argument can be `instance` or `class`. If can be omitted, and is then assumed to be `instance` +The `side` argument can be `instance` or `class`. It can be omitted, and is then assumed to be `instance`. " Class { #name : 'MicSourceBlock', diff --git a/src/Microdown/MicStartStopMarkupBlock.class.st b/src/Microdown/MicStartStopMarkupBlock.class.st index 9e445c3f..2143c081 100644 --- a/src/Microdown/MicStartStopMarkupBlock.class.st +++ b/src/Microdown/MicStartStopMarkupBlock.class.st @@ -1,5 +1,5 @@ " -May be in the future we will be able to say that SameMarkup is the same as a StartStop with the same delimiter but for now we do not know. +Maybe in the future we will be able to say that SameMarkup is the same as a StartStop with the same delimiter, but for now we do not know. " Class { #name : 'MicStartStopMarkupBlock', diff --git a/src/Microdown/MicTableBlock.class.st b/src/Microdown/MicTableBlock.class.st index 84d5c8c5..bca273f0 100644 --- a/src/Microdown/MicTableBlock.class.st +++ b/src/Microdown/MicTableBlock.class.st @@ -1,37 +1,35 @@ " -Support table with a simple and more relax setup than github. +Support for tables with a simpler and more relaxed setup than GitHub. A table is not forced to have a header definition. -``` +```text | aaab | jkhjh | | --- | | bar | ``` or -``` +```text |aaab|jkhjh| |---| |bar| ``` or -``` +```text | aaa | bbb | |ccc |ddd | ``` or -``` +```text | aaa | bbb | cc | ddd ``` Block-level elements cannot be inserted in a table. -When a table contains a header it is the first row and all rows should have that size else they are cut. - - -Known limits: how to put a pipe in a table? -No support for \| +When a table contains a header, it is the first row, and all rows should have that size, otherwise they are truncated. +### Known limitations +How to put a pipe in a table? No support for `\|`. " Class { #name : 'MicTableBlock', diff --git a/src/Microdown/MicTextBlock.class.st b/src/Microdown/MicTextBlock.class.st index fbdafc98..ee3e6083 100644 --- a/src/Microdown/MicTextBlock.class.st +++ b/src/Microdown/MicTextBlock.class.st @@ -1,5 +1,5 @@ " -I'm a special inline block representing the fact that there is not markup. +I'm a special inline block with no markup. " Class { #name : 'MicTextBlock', diff --git a/src/Microdown/MicUnEvaluatedBlock.class.st b/src/Microdown/MicUnEvaluatedBlock.class.st index f405e227..c05995ae 100644 --- a/src/Microdown/MicUnEvaluatedBlock.class.st +++ b/src/Microdown/MicUnEvaluatedBlock.class.st @@ -1,5 +1,5 @@ " -I represent blocks whose contents is not microdown markup as such. +I represent blocks whose content is not microdown markup as such. " Class { #name : 'MicUnEvaluatedBlock', diff --git a/src/Microdown/MicUnknownResourceUri.class.st b/src/Microdown/MicUnknownResourceUri.class.st index 5a9753b5..217c3a06 100644 --- a/src/Microdown/MicUnknownResourceUri.class.st +++ b/src/Microdown/MicUnknownResourceUri.class.st @@ -1,5 +1,5 @@ " -I am used for representing unknow uri rferences, for example `foo://bar.baz/path` +I am used for representing unknown URI references, for example `foo://bar.baz/path`. " Class { #name : 'MicUnknownResourceUri', diff --git a/src/Microdown/MicUnorderedListBlock.class.st b/src/Microdown/MicUnorderedListBlock.class.st index 0c19d0a9..104ffe73 100644 --- a/src/Microdown/MicUnorderedListBlock.class.st +++ b/src/Microdown/MicUnorderedListBlock.class.st @@ -4,7 +4,7 @@ I represent an unordered list of items. #### Example Typing -``` +```language=text - first - second on multiple line @@ -13,7 +13,7 @@ Not in third - first item of a new list ``` -produces +Produces: - first - second on multiple line @@ -21,20 +21,19 @@ produces Not in third - first item of a new list -Notice how the following line of the second item is indented with the previous one. +Notice how the second line of the second item is indented like the first line. ### Nested lists -A nested item starts aligned to its father. Below the `-` on the second level is aligned with the beginning of item1. +A nested item starts aligned with its parent. In the following example, the item on the second level is aligned with its parent (`item1`). -``` +```language=text - item1 - second level on two lines - item2 ``` -It produces - +Produces: - item1 - second level diff --git a/src/Microdown/MicZincPathResolver.class.st b/src/Microdown/MicZincPathResolver.class.st index 480baa11..e37e22be 100644 --- a/src/Microdown/MicZincPathResolver.class.st +++ b/src/Microdown/MicZincPathResolver.class.st @@ -1,19 +1,19 @@ " -I am a path resolver for microdown. -References in microdown (links, images and inputfiles) can be either absolute references to a specific file or http address, or relative to an absolute reference. +I am a path resolver for Microdown. +References in Microdown (links, images and input files) can either be absolute references to a specific file or http address, or relative to an absolute reference. -I am a visitor which is given a `MicAbsoluteResourceReference`, and traverses a document and **resolves** all relative references with respect to the base reference. Resolution is to replace the relative reference with an absolute. +I am a visitor which is given a `MicAbsoluteResourceReference`, and traverses a document and **resolves** all relative references with respect to the base reference. The resolution is to replace the relative reference with an absolute one. -The mention of `Zinc` in my name is a credit to `ZnUrl` which does the underlying resolution according to [rfc3986 Uniform Resource Identifier (URI): Generic Syntax/Reference Resolution](https://datatracker.ietf.org/doc/html/rfc3986#section-5). +The mention of `Zinc` in my name is a credit to `ZnUrl`, which does the underlying resolution according to [rfc3986 Uniform Resource Identifier (URI): Generic Syntax/Reference Resolution](https://datatracker.ietf.org/doc/html/rfc3986#section-5). -In particular [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986) is independent of file or http based uri's. It is the same algorithm used in all webbrowsers for image and link resolution of relative references. +In particular, [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986) is independent of file or http-based URIs. It is the same algorithm used by all web browsers for image and link resolution of relative references. -## Key method & implementation +## Key Method & Implementation I am used by calling my class side method `resolve:withBase:`. -If the base is a file based reference with an explicit filesystem (see comment in `MicFileResourceReference`) I am taking that into account. +If the base is a file-based reference with an explicit filesystem (see comment in `MicFileResourceReference`), I take that into account. -When parsing a resource reference (image, link or inputfile) which is relative, instances of `MicRelativeResourceReferences` are created in the parse nodes for `MicFigureBlock`, `MicLinkBlock` or `MicInputfileBlock`. I will replace all relative references in those blocks with absolute references based on the rfc3986 algorithm mentioned above. +When parsing a resource reference (image, link or input file) that is relative, instances of `MicRelativeResourceReference`s are created in the parse nodes for `MicFigureBlock`, `MicLinkBlock` or `MicInputfileBlock`. I will replace all relative references in these blocks with absolute references based on the rfc3986 algorithm mentioned above. " Class { #name : 'MicZincPathResolver', diff --git a/src/Microdown/Microdown.class.st b/src/Microdown/Microdown.class.st index 36a91619..05540506 100644 --- a/src/Microdown/Microdown.class.st +++ b/src/Microdown/Microdown.class.st @@ -1,8 +1,7 @@ " -I'm the favored entry point to use microdown. I'm a kind of facade to steer Microdown services. +I'm the favored entry point to use Microdown. I'm a kind of facade to steer Microdown services. - -In particular I invoke a resolver for paths after parsing documents . +In particular, I invoke a resolver for paths after parsing documents. " diff --git a/src/Microdown/MicrodownParser.class.st b/src/Microdown/MicrodownParser.class.st index 38dbcd5f..f4d221ef 100644 --- a/src/Microdown/MicrodownParser.class.st +++ b/src/Microdown/MicrodownParser.class.st @@ -4,14 +4,14 @@ I'm a parser for Microdown, implemented by S. Ducasse, L. Dargaud and G. Polito (2020). It is based on K. Osterbye's work on GitHubMarkdown. -Microdown covers Markdown basis syntax, with great Pillar's features. It's more extensible too. +Microdown covers the basic syntax of Markdown, with great Pillar features. It's also more extensible. ## MicroDown Syntax in a Nutshell! - + **Headers** (up to 6 levels) >>>> `# Header level 1` **Unordered list** -``` +```text - item a on another line - item b @@ -19,9 +19,7 @@ Microdown covers Markdown basis syntax, with great Pillar's features. It's more - item b2 - item c ``` - -produces - +Produces: - item a on another line - item b @@ -30,89 +28,105 @@ produces - item c **Ordered list** -``` +```text 1. item one 1. subitem 2. item two ``` -produces - +Produces: 1. item one 1. subitem 2. item two **Codeblock with arguments** -``` +```text ```language=Pharo&caption=Beautiful&label=Fig1 some piece of code ``` ``` - -produces - +Produces: ```language=Pharo&caption=Beautiful&label=Fig1 some piece of code ``` -**Anchor and its reference** >>>> `\@anchor` and its reference in text with `\*@anchor@*` +**Anchor and its reference** >>>> `@anchor` and its reference in text with `*@anchor@*` **Math environment** (rendered with LaTex in Pharo) -- inline: $\cos(\theta_i+C_3)$ >>>> `\$\cos(\theta_i+C_3)$` -- block: -``` - $ - \cos(\theta_i+C_3) - $ +- inline: $\cos(\theta_i+C_3)$ >>>> `$\cos(\theta_i+C_3)$` +- block: +```text +$$ +\cos(\theta_i+C_3) +$$ ``` +$$ +\cos(\theta_i+C_3) +$$ + **Annotated paragraph** -``` - !!note Then you can write your note - on several lines, like a normal paragraph +```text +!!note Then you can write your note +on several lines, like a normal paragraph ``` + **Quote** to indent some lines -``` +```text > This is > A nice quote ``` + **Environment** (called Annotation for inline) - inline: `\` - block: +```text + ``` - -``` + **Metadata** as a block -``` - { - type your metadata - } +```text +{ +type your metadata +} ``` -**Table** **@tocomment** +**Table** +Support for tables with a simpler and more relaxed setup than GitHub. +A table is not forced to have a header definition. -**Horizontal line** >>> `***` alone on a line will define a separator in your text **@todo** +```text +| aaa | bbb +| ccc | ddd +``` +Produces: +| aaa | bbb +| ccc | ddd -**Comments** don't appear after parsing >>> `% A commented line` +**Horizontal line** >>>> `***` alone on a line will define a separator in your text. +*** + +**Comments** don't appear after parsing >>>> `% A commented line` +% This can only be read in the original source, as you are doing. **Inline formats** - **bold** >>>> `**bold**` -- _italic_ >>>> `\_italic_` +- _italic_ >>>> `_italic_` - `monospace` aka inline code >>>> `\`monospace\`` -_Note: inline escape character is back slash: \\ ._ +_Note: inline escape character is the backslash: `\\`._ _Note: text in monospace is analyzed for you to generate hypertext Pharo code objects! Isn't it so cool to write a great doc? It is! Click on them!_ - `Point` for classes - `Point class` for class side - `Point>>#setX:setY:` for methods - `#'Microdown-Tests'` for packages -**Raw** for your other code (inline) >>>> `\{{ some code }}` +**Raw** for your other code (inline) >>>> `{{ some code }}` -**Link** >>>> `\[link's name](url|key1=value1&key2=value2)` +**Link** >>>> `[link's name](url|key1=value1&key2=value2)` -**Figure** >>>> `\!\[figure's name](url|key1=value1&key2=value2)` +**Figure** >>>> `![figure's name](url|key1=value1&key2=value2)` `![Pharo logo](https://files.pharo.org/media/logo/logo.png)` produces @@ -120,24 +134,24 @@ produces ![Pharo logo](https://files.pharo.org/media/logo/logo.png) -## Implementation +## Implementation Notes -I follow the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in appendix A. +I follow the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in the appendix. -In short, the strategy is that at any point in time, we might have a number of children of the root which are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open. +In short, the strategy is that at any point in time, we can have a number of children of the root that are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open. -When a new line is read we do the following: +When a new line is read, we do the following: 1. Check if the new line can be consumed by current. - - as part of this, a child of current can be made which can consume the new line. for example when consuming \`\`\` the root block node will create, a new code block that will become current and consume the body of the \`\`\` element then close. + - as part of this, a child of current can be made which can consume the new line. For example, when consuming `\`\`\``, the root block node will create a new code block that will become current and consume the body of the `\`\`\`` element, then close. 2. If current cannot consume the new line, we close current, move current to its parent, and repeat 1. -3. The root node can consume anything, for instance by making new nodes for storing the new line. +3. The root node can consume anything, for instance by making new nodes to store the new line. 4. The root node is not closed until input is exhausted. -I do not accept lazy definition. I do not accept three different ways to do the same. Except for bulleted list where `*` and `-` are accepted. +I do not accept lazy definition. I do not accept three different ways to do the same thing. Except for bulleted lists, where `*` and `-` are accepted. The spec says: -``` +```text -> document -> block_quote paragraph @@ -150,8 +164,7 @@ The spec says: -> paragraph ""aliquando id"" ``` -Now the implementation for now does not create a paragraph in the list_item element. - +The current implementation does not create a paragraph in the list_item element. " Class { #name : 'MicrodownParser', diff --git a/src/Microdown/MicrodownVisitor.class.st b/src/Microdown/MicrodownVisitor.class.st index d40be073..7744db92 100644 --- a/src/Microdown/MicrodownVisitor.class.st +++ b/src/Microdown/MicrodownVisitor.class.st @@ -1,9 +1,6 @@ " -I'm an abstract visitor for Microdown document three. -By default I visit only the nodes of the domain: it means that I will not visit the label of an annotated paragraph -or the parameters of an annotation or the URL of a figure because such elements are not represented by subclasses -of MicElement. - +I'm an abstract visitor for Microdown document trees. +By default, I only visit the nodes of the domain: it means that I will not visit the label of an annotated paragraph, or the parameters of an annotation, or the URL of an image, because such elements are not represented by subclasses of `MicElement`. " Class { #name : 'MicrodownVisitor',