Draft Package-URL Style Guide

[mjherzog]

We need to draft a simple style guide for PURL documentation - this would apply to the PURL and VERS specifications.
The first step is to collect examples for what we need to standardize. Some examples are:

• Use PURL instead of 'purl' except ?
• Use VERS instead of 'vers' except ?
• When to use a complete URL vs a link embedded in a text element.

[johnmhoran]

@mjherzog @pombredanne If we look, for example, at "How to build a purl string from its components" in the current purl-specification.md, there are scattered usages of purl (with backticks to denote code) throughout.

At first glance, none is a use of the "purl" string in a command or other "code", and I wonder: maybe all of these should be PURL (or Package-URL). Offhand I can't think of a command that uses "purl", but if one was created, or the string was used in a variable, I'd say lowercase "purl" is recommended but hey -- is that actually a rule?

[mjherzog]

I agree with your point about purl not referencing code, although I do often see code-style formatting for data elements/structures also. In this case we should use PURL for general consistency. The next question is whether to use code-style formatting for references to a PURL component. In the how-to-parse.md file we also have remainder which does not make sense,
So we probably need at least two conventions:

• How to define and show reserved terms - e.g. PURL
• When to use code-formatting

[mjherzog]

The documentation Contribution guidelines has some good ideas: https://github.com/ipfs/ipfs-docs/tree/main?tab=contributing-ov-file

[mjherzog]

See #10 for a draft style guide