Adding Metadata To Metanorma For Firelight: A Deep Dive

by Admin 56 views
Adding Metadata to Metanorma for Firelight: A Deep Dive

Hey guys! Let's talk about a neat challenge: how to get extra information into Metanorma documents so Firelight can use them. Right now, there's a bit of a workaround happening with the Plateau documents. We're essentially making modifications to the HTML after it's been created, which isn't ideal. This post is all about finding a cleaner, more efficient way to handle this, ensuring the final output is exactly what we need, without the extra post-processing steps. It's about empowering authors to include all the necessary details right from the start.

The Current Situation: Post-Processing Woes

So, what's the deal with the current process? Well, imagine you've got a document, and you want to jazz it up with some extra links and styling. Currently, the Plateau documents undergo some post-processing of HTML to add cool stuff like:

  • Links to the project's homepage.
  • Links to supporting datasets (like i-UR & CityGML).
  • An alternative rendering of the document, often a PDF version.
  • Links to related documents (think of it like cross-referencing).
  • Links to templates.
  • Custom headings for link blocks.
  • Specific colors for styling.

See the image in the prompt for a visual of this! The issue is that this post-processing step isn't the most elegant solution. It'd be way better if we could build all of this information directly into the Metanorma source files.

The Goal: Embedding Metadata for Seamless Integration

The main goal here is to find a way to let authors specify relevant information in their AsciiDoc files. This means using AsciiDoc attributes to pass this extra metadata through Metanorma and into the final XML output. Firelight can then process this XML to create the desired output. We're aiming for a smoother workflow where the necessary information travels with the document from the start, avoiding the need for later modifications. Ultimately, the goal is to make the process more streamlined, reduce potential errors, and improve the overall efficiency of the documentation pipeline.

AsciiDoc Attributes: The Potential Solution

Here's where the magic might happen. AsciiDoc attributes could be the key! The idea is that authors would add specific attributes to their AsciiDoc files, and Metanorma would pass these attributes along to the XML output. Firelight could then use these attributes to generate the necessary links, styling, and other elements. For example, you could define attributes like project_homepage, supporting_datasets, related_document, and pdf_link. Each attribute would contain the relevant URL or information. It's like adding extra labels or tags to your document, which Metanorma and Firelight can then use to do their jobs.

Now, the big question is: Can Metanorma pass these extra attributes through to the XML? That’s what we're trying to figure out!

If it works, we can sit down with @ReesePlews and @ronaldtse to decide how to best structure the attributes (perhaps using multiple attributes or a single, serialized structure). If not, we'll need to find another way to get the metadata across.

Potential Attributes and Their Uses

Let's brainstorm some attributes that could be super helpful:

  • project_homepage: This would hold the URL of the project's homepage, allowing Firelight to generate a link in the document's header or footer.
  • supporting_datasets: This could be a list or a structured object containing URLs or references to supporting datasets. Think of it as a way to link to external resources directly from the document.
  • related_document: This would link to other documents within the collection, promoting easy navigation and cross-referencing.
  • pdf_link: The path to the PDF version of the document. This is particularly useful for providing alternative renderings or downloads.
  • template_link: Link to the template used for the document
  • styling_color: A hex code or a named color for use in styling elements in the document.

Handling PDF Links and Collection Links

It's also worth noting some specific link types that need attention:

  • PDF Links: In some systems like CalConnect, the local path to the PDF is stored in the XML, so the build system can copy the PDF and create a link. This is a common requirement.
  • Links to Documents in a Collection: Ideally, documents should be part of a collection, but if that's not possible, we need a way to link between documents. This could be achieved by using the related_document attribute.

Exploring Alternatives: If Attributes Aren't the Answer

If using AsciiDoc attributes isn't possible, we need a backup plan. The main alternative would be to explore how to pass extra metadata through to custom XML processors in Metanorma. This might involve:

  • Custom XML Tags: Metanorma might allow us to inject custom XML tags directly into the output. This would give us complete control over the structure and content of the metadata.
  • Custom Extensions or Plugins: Metanorma may support extensions or plugins that allow you to modify the XML output during the build process.

Conclusion: Paving the Way for Efficient Documentation

So, here's the deal, guys! This is all about making the document process better and smoother. We're aiming to find a way to embed all the extra metadata right into the source files. Using AsciiDoc attributes looks like a great option, but we need to figure out if it's possible. If not, we'll find another solution. This whole process is about streamlining how we get all the data into the final output. The key is to reduce the need for post-processing and give authors more control over how their documents are rendered. That will save time and make sure everything looks perfect without extra effort. It's about a smarter, more efficient way of doing things! The end goal is to ensure that Firelight has all the information it needs, without any extra steps. It's about creating a documentation system that's both powerful and easy to use. I'm excited to see how this evolves and where we end up!