Improve cross-linking of types in 'Pandoc Lua Filters' docs

[0xdevalias]

In the spirit of:

• https://pandoc.org/CONTRIBUTING.html

  • Write or improve documentation. If you ran into a problem which took more time to figure out than expected, please consider to save other users from the same experience. People writing the documentation tend to lack an outside view, so please help provide one. Good documentation is both difficult and extremely important.

Describe your proposed improvement and the problem it solves.

In the Lua Filters documentation, there are generally 2 different sections for the various types, and their constructors. eg.

• Emph (type)`: https://pandoc.org/lua-filters.html#type-emph
• Emph (contructor): https://pandoc.org/lua-filters.html#pandoc.Emph
• CodeBlock (type): https://pandoc.org/lua-filters.html#type-codeblock
• CodeBlock (constructor): https://pandoc.org/lua-filters.html#pandoc.CodeBlock

A pattern I've noticed is that the 'type' usually includes a cross-link to the 'constructor':

Values of this type can be created with the pandoc.Emph constructor.

Values of this type can be created with the pandoc.CodeBlock constructor.

But the 'constructor' doesn't seem to include a crosslink to the 'type', and usually only refers to the more generic Block / Inline:

Returns:

• new object (Inline)

Returns:

• CodeBlock element (Block)

While I was recently exploring writing a lua filter I found myself spending a lot of time jumping back and forth in the docs, and felt like it would be easier if those sections cross-linked to one another.

Describe alternatives you've considered.

I'm aware of this issue/PR, but the nuance is different:

• Restructure Lua and JSON filter docs #8750
  • Simplify and reorganize Lua filter introduction #9106

This docs issue is also unrelated, except for improving the docs UX for new users in general:

• Improve pandoc.scaffolding section in 'Pandoc Lua Filters' docs (RE: Custom Writers) #10531

[jgm]

@tarleb what do you think?

[tarleb]

This is a good idea, but we would have to update HsLua and the tools/update-lua-module-docs.lua script: this part of the docs is auto-generated, but I think the necessary information isn't part of the Haskell-side definitions (yet).

[0xdevalias]

but we would have to update HsLua and the tools/update-lua-module-docs.lua script

Linking for reference:

• https://github.com/jgm/pandoc/blob/main/tools/update-lua-module-docs.lua
  • 790abcf

but I think the necessary information isn't part of the Haskell-side definitions (yet)

I don't know enough about the specifics of this currently; but my original naive thought/notice was that for the ones I checked, the URL hash needed to link between them was basically something like #type-foo and #pandoc.Foo; so if I was going to manually do it, I was just going to follow that sort of convention.

Which looks like at least half of which already exists in known_types:

pandoc/tools/update-lua-module-docs.lua

Lines 75 to 105 in 58ca8df

	local known_types = {
	Alignment = 'type-alignment',
	Attr = 'type-attr',
	AttributeList = 'type-attributes',
	Block = 'type-block',
	Blocks = 'type-blocks',
	Caption = 'type-caption',
	Cell = 'type-cell',
	ColSpec = 'type-colspec',
	Doc = 'type-doc',
	ChunkedDoc = 'type-chunkeddoc',
	Figure = 'type-figure',
	Inline = 'type-inline',
	Inlines = 'type-inlines',
	ListAttributes = 'type-listattributes',
	Meta = 'type-meta',
	MetaValue = 'type-metavalue',
	Pandoc = 'type-pandoc',
	ReaderOptions = 'type-readeroptions',
	Row = 'type-row',
	SimpleTable = 'type-simpletable',
	Span = 'type-span',
	Str = 'type-str',
	Table = 'type-table',
	TableBody = 'type-tablebody',
	TableHead = 'type-tablehead',
	TableFoot = 'type-tablefoot',
	Template = 'type-template',
	WriterOptions = 'type-writeroptions',
	Version = 'type-version',
	}

---

Exploring deeper with GitHub Copilot

To modify the script to auto-generate crosslinks between sections as discussed in issue 10529, we need to:

1. Identify sections that need crosslinks: Specifically, we need to crosslink type definitions with their constructors and vice versa.
2. Modify the script to add these crosslinks during the documentation generation process.

Here is a step-by-step approach to implementing this:

1. Update known_types map to include crosslinks for constructors:
   Add a field to track the constructor for each type in the known_types table.

2. Modify render_type function:
   Add logic to insert a crosslink to the constructor in type definitions.

3. Modify render_function function:
   Add logic to insert a crosslink to the type definition in constructor documentation.

4. Update the process_document function:
   Ensure the new crosslinking logic is applied during the document processing.

References:

• render_type:

  pandoc/tools/update-lua-module-docs.lua

  Line 249 in 58ca8df

  local function render_type (name, level, modulename)

• render_function:

  pandoc/tools/update-lua-module-docs.lua

  Line 202 in 58ca8df

  local function render_function (doc, level, modulename)

• process_document:

  pandoc/tools/update-lua-module-docs.lua

  Line 389 in 58ca8df

  local function process_document (input, blocks, start)

This is the diff of the changes it suggested making to implement this. I haven't sought to verify them, but wanted to include them here for completeness in case they are helpful:

--- Unsaved view (768)
+++ Unsaved view (770)
@@ -217,6 +217,7 @@
       end
     )
   )
+  local crosslink = known_types[modulename] and Para{Str("Values of this type can be created with the "), Link(modulename, '#' .. modulename), Str(" constructor.")} or Blocks{}
   return Blocks{
     Header(level, name, {id}),
     Plain{Code(string.format('%s (%s)', name, args))},
@@ -226,6 +227,7 @@
     .. List(#doc.results > 0 and {Para 'Returns:'} or {})
     .. render_results(doc.results)
     .. Blocks(doc.since and {Para{Emph{'Since: ' .. doc.since}}} or {})
+    .. crosslink
 end
 
 --- Renders documentation of a module field.
@@ -295,8 +297,10 @@
   end
   local header_id = 'type-' .. nameprefix .. '.' .. name
   known_types[name] = known_types[name] or header_id
+  local crosslink = known_types[name] and Para{Str("This constructor creates values of type "), Link(name, '#' .. name), Str(".")} or Blocks{}
   return {Header(level, name, {header_id})} ..
-    type_description
+    type_description ..
+    crosslink
 end
 
 --- Renders module documentation.

The 1st/2nd diff blocks are in render_function, the 3rd is in render_type.

[tarleb]

Copilot isn't too far off, but it's missing one critical piece of info: the function definitions for the constructors are in the pandoc-lua-marshal project and would have to be modified there. Furthermore, we don't use Inline "subtypes" anywhere else, so I'm not 100% certain that it won't have unexpected effects elsewhere (but I think it won't).