psuedo fileformat, issue #41

[finanalyst]

This wording - I think - is consistent with the logic of the thread, gives examples for local links, allows implicitly for extensions to external links by clear analogy, and leaves open the possibility for internal ones, should someone in the future think up a use case and syntax for one.

[thoughtstream]

I would be inclined to add a little more information at the end.
Perhaps:

For example, if the output format is Markdown, these links would be rendered
with C<.md> extensions replacing the C<.*> pseudo-extensions:

    [dealing with the filesystem](type/IO.Path.md)

            [a directory listing](type/IO.Path.md#routine_dir)

Or, if the output format is HTML, these links would be rendered
with C<.html> extensions instead:

    <a href="type/IO.Path.html">             dealing with the filesystem </a>
    <a href="type/IO.Path.html#routine_dir"> a directory listing         </a>

[finanalyst]

@thoughtstream FYI the Rakuast renderer can now handle all (I think) of the RakuDoc v2 components. Tweaks are needed, eg. for .*, but I think I have the functionality to handle everything.

This means that we will need to go through the document again to eliminate the workarounds that were used to overcome the deficiencies in the previous renderer.

[thoughtstream]

I've now reviewed the two commits and found a couple of layout bugs and one place where the wording needed a little further clarification. I also modified the text of one of the link examples, so that both examples are now of identical length, which makes the relevant extensions align perfectly in the RakuDoc and Markdown examples, which in turn makes the changes in the extensions stand out more clearly.

Otherwise, I am entirely happy with the new text.

Here is the proposed revision:

--- PR41.rakudoc	2024-07-27 11:35:41.000000000 +1000
+++ PR41_tweaks.rakudoc	2024-07-27 11:40:45.000000000 +1000
@@ -1,28 +1,29 @@
 
 The exact name of the resource to which a link is pointing must be used by the renderer. So
-    L< For reference | README.md > or L< text reference | README >
-
+    C<L< For reference | README.md >> or C<L< text reference | README >>
 must link to C<README.md> and to C<README>, with the renderer making no assumption about the
 file format.
 
 However, a collection of RakuDoc sources may be intended as the base for multiple formats, such
-as C< .html >, C< .md >, or C< .pdf >, and so links within the collection need to delegate to the
-renderer the file format (if one is needed). This is accomplished explicitly using the C< .* >
+as C< .html >, C< .md >, or C< .pdf >, and so links within the collection may need to delegate
+the selection of an appropriate file format (if one is needed) to the renderer. This is accomplished explicitly using the C< .* >
 pseudo extension, for example:
+
     L< dealing with the filesystem | type/IO.Path.* >
 
 or for a heading within another resource:
-    L< a directory listing | type/IO.Path.*#routine_dir >
+
+    L< getting a directory listing | type/IO.Path.*#routine_dir >
 
 For example, if the output format is Markdown, these links would be rendered
 with C<.md> extensions replacing the C<.*> pseudo-extensions:
 
     [dealing with the filesystem](type/IO.Path.md)
-    [a directory listing](type/IO.Path.md#routine_dir)
+    [getting a directory listing](type/IO.Path.md#routine_dir)
 
 Or, if the output format is HTML, these links would be rendered
 with C<.html> extensions instead:
 
     <a href="type/IO.Path.html">             dealing with the filesystem </a>
-    <a href="type/IO.Path.html#routine_dir"> a directory listing         </a>
+    <a href="type/IO.Path.html#routine_dir"> getting a directory listing </a>