Not-invented-here: ".scd" format confusing file ending for application usage documentation. replace with ".md"

[hholst80]

The discussion highlights the use of ".scd" as a file extension for source code documentation files and its association with Markdown content. However, when considering software documentation rather than documenting the source code itself, it is advisable to use the more widely recognized and standard ".md" file extension for Markdown files.

Using ".md" offers several advantages, including greater familiarity among developers and users, wider tool and platform support, and adherence to established conventions for Markdown documentation. While a custom ".scd" extension might be acceptable within a specific project, it can introduce confusion and compatibility issues when collaborating with others.

To ensure consistency, clarity, and compatibility, it is suggested to replace the ".scd" documentation files with the ".md" file extension, making it easier for contributors and users to identify, work with, and render the Markdown content. This change aligns with best practices and promotes seamless collaboration and understanding of the software documentation.

[emersion]

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

[hholst80]

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.

[kennylevinsen]

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[^1].

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[^2].

[^1]: You do realize that sourcehut is run by the scdoc author and original creator of sway, right? [^2]: You can look at the 265 AUR packages that have a build dependency on scdoc as a start.