Not-invented-here: ".scd" format confusing file ending for application usage documentation. replace with ".md" about swayidle HOT 3 CLOSED

Nope. scdoc is not Markdown, and .scd is used by all scdoc files.

from swayidle.

It seems like there's no mention of a specific file extension for scdoc files. The man page doesn't define one.

Case study: JSON schemas. Just because a JSON document has a particular schema doesn't mean the file needs a different suffix than .json. It's still JSON, just understood by the recipient as a specific kind of file. It's encoded as JSON.

If we look at the notation, it's clearly a subset of Markdown and works well with platforms like GitHub. And ironically, sourcehut, where the project upstream is hosted, does not recognize it as Markdown simply because it uses the file ending .scd to determine the render.

Let's not get caught up in strawman arguments or give importance to the made-up file extension ".scd" that is not even promoted by the upstream maintainers of this niche tool.

from swayidle.

If we look at the notation, it's clearly a subset of Markdown and works well with platforms like GitHub.

If we read scdoc's format documentation - scdoc.5.scd - it can be seen that the format is not Markdown compatible. Take a look at the table syntax for example, which has nothing to do with Markdown tables but instead is specialized for replacing troff(1) in manpage generation. Granted, there are similarities to Markdown, but it is not Markdown.

And ironically, sourcehut, where the project upstream is hosted, does not recognize it as Markdown simply because it uses the file ending .scd to determine the render.

It also does not recognize it as troff, xml or JavaScript because it uses the file extension ".scd". Not being recognized as a wrong format is intentional¹.

Let's not get caught up in strawman arguments or give importance to the made-up file extension ".scd" that is not even promoted by the upstream maintainers of this niche tool.

Let's not get caught up in ignorance and false equivalence arguments. We are not going to use an incorrect file extension to communicate a wrong file format in order to trigger defective syntax highlighting in editors without support for the syntax. The file-ending for scdoc's own scdoc documentation is .scd, and all known external uses of scdoc use .scd².

from swayidle.