Coordination / Registry: Pandoc-related Naming

Coordination / Registry: Pandoc-related Naming

[Martin Hepp]

Dear all:

In the Pandoc eco-system, we use class and attribute names in many places for many different purposes.

As more and more 
- filters, 
- extensions, and 
- applications (like RStudio and Quarto) 
define and use meta-data conventions, it would be great to agree upon a lightweight mechanism for coordinating the naming and minimizing the risk of collisions.

A helpful first step would be to advocate the use of prefixes for names that are used in and shared by the core Pandoc ecosystem. Panflute is already a good example with the use of "panflute-" as a prefix:

---
panflute-filters: [remove-tables, include]
panflute-path: 'panflute/docs/source'
...

Codebraid is also consistently using a "cb" prefix in class names (like .cb.run) that control behavior, but not for attributes:

`1 + "a"`{.python .cb.run session=inline_error example=true}

Lack of coordination can mean that 

1. the same name may trigger conflicting things (like the logo property for Eisvogel vs. the logo property for Beamer, see https://github.com/Wandmalfarbe/pandoc-latex-template/issues/265)
or
2. multiple tools require different names for the same data.

Both will make maintaining consistent Markdown documents and workflows difficult.

Hence, I think it would be really good to start coordinating the naming of classes and properties in the Pandoc ecosystem. 

Coordinating can mean standardizing, but it could also be limited to helping avoid collisions by e.g. advocating prefixes.

Is there anything like a prefix naming scheme registry for Pandoc? The WWW for instance uses such mechanisms for many parts of the ecosystem, like 

- https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
- https://www.iana.org/assignments/http-parameters/http-parameters.xhtml
- https://www.iana.org/assignments/media-types/media-types.xhtml

This does not have to be a big effort; it would be sufficient to

- create and maintain a simple Markdown file in the Pandoc repository,
- define a few ground rules like 
	- prefixes for popular components, 
	- a process to follow for new names in the core namespace,
	- the use of a prefix like "x" for names that are proprietary, ...), 
and to 
- try to track popular components, their property names, and prefixes in the Markdown file.

What do you think?

Best wishes
Martin

Re: Coordination / Registry: Pandoc-related Naming

[Albert Krewinkel]

Hi,

Good points. I think an informal "registry" page in pandoc's wiki would
be a good idea. 👍

Cheers,
Albert

Martin Hepp <mfhepp-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Dear all:
>
> In the Pandoc eco-system, we use class and attribute names in many places for many different purposes.
>
> As more and more
> - filters,
> - extensions, and
> - applications (like RStudio and Quarto)
> define and use meta-data conventions, it would be great to agree upon a lightweight mechanism for coordinating the naming and minimizing the risk of collisions.
>
> A helpful first step would be to advocate the use of prefixes for names that are used in and shared by the core Pandoc ecosystem. Panflute is already a good example with the use of "panflute-" as a prefix:
>
> ---
> panflute-filters: [remove-tables, include]
> panflute-path: 'panflute/docs/source'
> ...
>
> Codebraid is also consistently using a "cb" prefix in class names (like .cb.run) that control behavior, but not for attributes:
>
> `1 + "a"`{.python .cb.run session=inline_error example=true}
>
> Lack of coordination can mean that
>
> 1. the same name may trigger conflicting things (like the logo property for Eisvogel vs. the logo property for Beamer, see https://github.com/Wandmalfarbe/pandoc-latex-template/issues/265)
> or
> 2. multiple tools require different names for the same data.
>
> Both will make maintaining consistent Markdown documents and workflows difficult.
>
> Hence, I think it would be really good to start coordinating the naming of classes and properties in the Pandoc ecosystem.
>
> Coordinating can mean standardizing, but it could also be limited to helping avoid collisions by e.g. advocating prefixes.
>
> Is there anything like a prefix naming scheme registry for Pandoc? The WWW for instance uses such mechanisms for many parts of the ecosystem, like
>
> - https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
> - https://www.iana.org/assignments/http-parameters/http-parameters.xhtml
> - https://www.iana.org/assignments/media-types/media-types.xhtml
>
> This does not have to be a big effort; it would be sufficient to
>
> - create and maintain a simple Markdown file in the Pandoc repository,
> - define a few ground rules like
> 	- prefixes for popular components,
> 	- a process to follow for new names in the core namespace,
> 	- the use of a prefix like "x" for names that are proprietary, ...),
> and to
> - try to track popular components, their property names, and prefixes in the Markdown file.
>
> What do you think?
>
> Best wishes
> Martin


--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/87a6hozj2g.fsf%40zeitkraut.de.