Merge 1ed589c

Author: Ducasse

.github/scripts/preLoading.st

@@ -1,11 +1,3 @@
-"IceRepository registry 
-	detect: [ :each | #('Microdown' 'NewTools-DocumentationReader') includes: each name ]
-	ifFound: [ :aRepository | aRepository forget ].
-#( 'BaselineOfMicrodownDev' 'BaselineOfMicrodown' 'Microdown' 'Microdown-Tests' 'Microdown-MicrodownRichTextComposer' 'Microdown-ResolvePath' 
-'Microdown-ResolvePath-Tests' 'NewTools-DocumentationReader-Tests' 'BaselineOfNewToolsDocumentationReader' 'Microdown-RichTextComposer' 'Spec2-Microdown'
-'NewTools-DocumentationReader' 'BaselineOfBeautifulComments' 'BeautifulComments') do: [ :each | 
-	(RPackageOrganizer default packageNamed: each ifAbsent: [ nil ]) 
-		ifNotNil: [ :aPackage | aPackage removeFromSystem ] ]"
 
 #( 'Microdown' 'BeautifulComments' 'DocumentBrowser' ) do: [ :name |
 		(IceRepository repositoryNamed: name)

.github/workflows/tests-all.yml

@@ -6,9 +6,9 @@ env:
 
 on:
   push:
-    branches: [ Pharo12 ]
+    branches: [ Pharo13 ]
   pull_request:
-    branches: [ Pharo12 ]
+    branches: [ Pharo13 ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -19,11 +19,13 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        smalltalk: [ Pharo64-12 ]
+        smalltalk: [ Pharo64-alpha ]
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.smalltalk }} on ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
+        with:
+         fetch-depth: '0'
       - name: Setup smalltalkCI
         uses: hpi-swa/setup-smalltalkCI@v1
         with:

.github/workflows/tests.yml

@@ -22,10 +22,12 @@ jobs:
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v3
+        with:
+         fetch-depth: '0'
       - uses: hpi-swa/setup-smalltalkCI@v1
         id: smalltalkci
         with:
-          smalltalk-image: Pharo64-12
+          smalltalk-image: Pharo64-alpha
       - run: smalltalkci -s ${{ steps.smalltalkci.outputs.smalltalk-image }}
         shell: bash
         timeout-minutes: 15

doc/api.md

@@ -1 +1,111 @@
-# Microdown APIThere is a lot of functionality in Microdown, and this document gives an overview of the Microdown architecture.- Architecture - key objects in Microdown- Microdown facade methods- Resource references and resolvers. Dealing with links, images, and included documentsSeveral parts of Microdown allows for extending the Microdown tool suite. [Extension has is own documentation page](extension.md).The full suite of microdown tools are not loaded by default. In particular there is also support for - Translation of Microdown to Latex and Beamer- Translation of Microdown to HTML- Translation from Pillar to Microdown- Misc other tools## ArchitectureThe overall idea in Microdown is like this:![](https://www.planttext.com/api/plantuml/png/VP1D2u9048Rl-oi6xq9q35c4EdHG2fJkYmwofBioEqj2zDzJAoNxcECy3xmlR-nO4Vkc5iATjMaLgGO82rQcgX6k0leZwqsvjMIGOBqIDo5c8qXrGRQq5nF0IvzWPZqL256KCMbJIGaBOMSBtw3XNia9KSe5px4RsC5pw_c39egn-uttUPeiwRDH6CevUmD7HGvf5ARle8pn6pXffzb-uOy2VuInmZiVvelHbFtcTm00)$$%commentYou can edit the figure using this source on planttext.com @startumlskinparam rectangle {    roundCorner 20}rectangle "Microdown"  {    rectangle Source <<String>>     rectangle Document <<Tree>>    rectangle Text <<Output>>    rectangle Latex <<Output>>    rectangle HTML <<Output>>    Source --> Document : Parser    Document --> Text : Visitor    Document --> Latex : Visitor    Document --> HTML : Visitor    }@enduml $$The format of the source code is explained in the [section on syntax](syntax.md).The parser translates the source code into an abstract syntax tree which we refer to as a "document". Translation into various output formats are done using visitors. By default only the visitor for translation into pharo `Text` is in the image. Sometimes `Text` is refered to as `RichText` to emphasize its difference from plain character `String`.## Microdown facade### Parse and output generationThe class `Microdown` has facade methods for the main actions in the architecture.- `Microdown class >> #parse:` translates a microdown source string into a document.- `Microdown class >> #asRichText:` translates a document into rich text. `asRichText:` can also accept a source string directly, cirumventing the `parse:` method. There are two facade methods for _resolution_. - `Microdown class >> #resolveDocument:withBase:` and - `Microdown class >> #resolveString:withBase:`The will be explained in the next section ## Resolution and referencesReferences to other documents or images can be either _absolute_ or _relative_. A typical absolute reference is `[Pharo](https:pharo.org)` or `![](file:/path/to/image.png)`. Absolute references cause no problems for the visitors to find the image or follow the link.However, when writing larger documents it is customary to keep images for the document in a seperate image folder, and refer to the images as `![](img/figure2.png)`. Such a reference is _relative_. It is relative to to location of the document containing the reference.**Resolution** is the process of replacing all relative references with absolute references. This process takes two inputs:- A document D containing relative references- The absolute location of document D (the base of the document).The two methods - `Microdown class >> #resolveDocument:withBase:` and - `Microdown class >> #resolveString:withBase:`are the prefered way to resolve documents.### Resource referencesIf we go one level below this, references are first order objects, all subclasses of `MicResourceReference`.In the standard image there are three kinds of absolute references:- http (and https) - for example: 'https://pharo.org/web/files/pharo.png'- file - for example 'file:/user/joe/docs/api.md'- the pharo image - for example 'pharo:///Object/iconNamed:/thumbsUp' (![](pharo:///Object/iconNamed:/thumbsUp))#### Creating referencesThe prefered way is to use the extension method `asMicResourceReference`, which is defined for- String - for example `'file:/user/joe/docs/api.md' asMicResourceReference`- ZnUrl - for example `(ZnUri fromString: 'https://pharo.org/web/files/pharo.png') asMicResourceReference`- FileReference - for example `(FileSystem memory) asMicResourceReference`#### Using referencesThere are two main key methods on references:- `loadImage` - returns a `Form` by reading the image (read using `ImageReadWriter class >> #formFromStream:`)- `loadMicrodown` - loads _and resolves_  a document#### BackgroundThe resolution is done using `ZnUrl >> #withRelativeReference:`, which implements the full resolution standard [RFC 3986 Section 5](https://datatracker.ietf.org/doc/html/rfc3986#section-5).##### Ambiguity of file uriIn pharo there is an issue that uri ' file://path/to/my/document.md' is ambiguous, because it can not be determined in which file system the path is supposed to be resolved (memory or disk).  This problem is dealt with, in the following manner:- `' file://path/to/my/document.md' asMicResourceReference` will always use the disk file system- `aFileReference asMicResourceReference` will create a `MicFileResourceReference` which remembers the file system in the file reference.- `aMicFileResourceReference loadDocument` will use the right filesystem for resolution.
+# Microdown API
+
+There is a lot of functionality in Microdown, and this document gives an overview of the Microdown architecture.
+
+- Architecture - key objects in Microdown.
+- Microdown facade methods.
+- Resource references and resolvers. Dealing with links, images, and included documents.
+- Document checkers: Microdown provides checkers that validate documents.
+
+Several parts of Microdown allows for extending the Microdown tool suite. Chapter *@[Extension](extension.md)@* presents the mechanisms in place.
+
+The full suite of microdown tools are not loaded by default. In particular there is also support for:
+- Translation of Microdown to Latex and Beamer,
+- Translation of Microdown to HTML,
+- Translation from Pillar to Microdown, and
+- Document checkers.
+
+## Architecture
+The overall idea in Microdown is like this:
+
+![](https://www.planttext.com/api/plantuml/png/VP1D2u9048Rl-oi6xq9q35c4EdHG2fJkYmwofBioEqj2zDzJAoNxcECy3xmlR-nO4Vkc5iATjMaLgGO82rQcgX6k0leZwqsvjMIGOBqIDo5c8qXrGRQq5nF0IvzWPZqL256KCMbJIGaBOMSBtw3XNia9KSe5px4RsC5pw_c39egn-uttUPeiwRDH6CevUmD7HGvf5ARle8pn6pXffzb-uOy2VuInmZiVvelHbFtcTm00)
+
+You can edit the figure using this source on planttext.com
+```
+@startuml
+skinparam rectangle {
+    roundCorner 20
+}
+rectangle "Microdown"  {
+    rectangle Source <<String>> 
+    rectangle Document <<Tree>>
+    rectangle Text <<Output>>
+    rectangle Latex <<Output>>
+    rectangle HTML <<Output>>
+    Source --> Document : Parser
+    Document --> Text : Visitor
+    Document --> Latex : Visitor
+    Document --> HTML : Visitor   
+}
+@enduml 
+```
+
+The format of the source code is explained in the Chapter *@[Syntax](syntax.md)@*.
+
+The parser translates the source code into an abstract syntax tree which we refer to as a "document". Translation into various output formats are done using visitors. By default only the visitor for translation into Pharo `Text` objects is in the image. Sometimes `Text` is refered to as `RichText` to emphasize its difference from plain character `String`.
+
+
+## Microdown facade
+### Parse and output generation
+The class `Microdown` has facade methods for the main actions in the architecture.
+
+- `Microdown class >> #parse:` translates a microdown source string into a document.
+- `Microdown class >> #asRichText:` translates a document into rich text. `asRichText:` can also accept a source string directly, cirumventing the `parse:` method. 
+
+There are two facade methods for _resolution_. 
+- `Microdown class >> #resolveDocument:withBase:` and 
+- `Microdown class >> #resolveString:withBase:`
+
+The will be explained in the next section.
+
+## Resolution and references
+
+References to other documents or images can be either _absolute_ or _relative_. 
+
+#### Absolute vs. relative references. 
+
+A typical absolute reference is `[Pharo](https:pharo.org)` or `![](file:/path/to/image.png)`. Absolute references cause no problems for the visitors to find the image or follow the link.
+However, when writing larger documents it is customary to keep images for the document in a seperate image folder, and refer to the images as `![](img/figure2.png)`. Such a reference is _relative_. It is relative to to location of the document containing the reference.
+
+**Resolution** is the process of replacing all relative references with absolute references. This process takes two inputs:
+- A document D containing relative references and
+- The absolute location of document D (the base of the document).
+
+The two methods 
+- `Microdown class >> #resolveDocument:withBase:` and 
+- `Microdown class >> #resolveString:withBase:`
+are the prefered way to resolve documents.
+
+### Resource references
+
+If we go one level below this, references are first order objects, all subclasses of `MicResourceReference`.
+
+In the standard image there are three kinds of absolute references:
+- http (and https) - for example: 'https://pharo.org/web/files/pharo.png'
+- file - for example 'file:/user/joe/docs/api.md'
+- the pharo image - for example 'pharo:///Object/iconNamed:/thumbsUp' `(![](pharo:///Object/iconNamed:/thumbsUp))`
+- 
+#### Creating references
+
+The prefered way is to use the extension method `asMicResourceReference`, which is defined for
+- String - for example `'file:/user/joe/docs/api.md' asMicResourceReference`
+- ZnUrl - for example `(ZnUri fromString: 'https://pharo.org/web/files/pharo.png') asMicResourceReference`
+- FileReference - for example `(FileSystem memory) asMicResourceReference`
+
+#### Using references
+
+There are two main key methods on references:
+- `loadImage` - returns a `Form` by reading the image (read using `ImageReadWriter class >> #formFromStream:`)
+- `loadMicrodown` - loads _and resolves_  a document
+
+#### Background
+
+The resolution is done using `ZnUrl >> #withRelativeReference:`, which implements the full resolution standard [RFC 3986 Section 5](https://datatracker.ietf.org/doc/html/rfc3986#section-5).
+
+##### Ambiguity of file uri
+
+In pharo there is an issue that uri ' file://path/to/my/document.md' is ambiguous, because it can not be determined in which file system the path is supposed to be resolved (memory or disk).  This problem is dealt with, in the following manner:
+- `' file://path/to/my/document.md' asMicResourceReference` will always use the disk file system
+- `aFileReference asMicResourceReference` will create a `MicFileResourceReference` which remembers the file system in the file reference.
+- `aMicFileResourceReference loadDocument` will use the right filesystem for resolution.
+