Markdown style guide

[ehuss]

I think it would be good to have some guidance on preferences for how the Markdown text is written. These are some suggestions, many of which are from the Reference.

• Restrict sources to .md or .html. We should make intentional decisions to include other types of sources as a team.

• Prevent #![feature] in examples (the spec should not be documenting unstable)

• Reject CRLF

  • This might have complications based on Windows' users core.autocrlf setting.

• Reject tab

• File must end with a newline

• Lines must not end in spaces

  • This is important because trailing spaces are significant in Markdown, but I think that is a flaw.

• Avoid double blank lines

• Do not use indented code blocks (3+ backticks code blocks instead)

• Code blocks should have an explicit language

• Use ATX-style headings (not Setext)

• Use sentence case for headings

• Line wrapping
  Word wrapping column? 80? 90? 100? No wrapping? No preference? Semantic linefeeds?
  If not semantic linefeeds, then what is the policy for PRs? Should they rewrap any content they touch?

  • ehuss's preference: Semantic linefeeds are extremely helpful for dealing with diffs. Essentially, just once sentence per line.

• Link kinds

  • There are different ways to link to things, such as reference links, or inline links.
    ehuss's preference is to only use reference links.
    Inline links disrupt the flow of the source text, so it can be recommended to avoid them.
    Use reference link shortcuts if appropriate.

    How should the references be organized? Within the section they are first used? At the bottom of the file? Should they be sorted?

    • ehuss's preference: Either at the bottom of a section, or at the bottom of the file, it doesn't really matter. Keep it sorted (case-insensitive?), which can help if there is a long list.

• Always use relative links, to .md

  • Using .md relative links allows it to work in GitHub's rendering.
  • For now, we will not be able to do relative links to std and other Rust docs. These are important for properly supporting offline viewing of the Rust documentation. Also, our link validation only works with relative links. We may want to investigate better tooling for that.

• Use smart punctuation instead of Unicode characters.
  Use --- for em-dash instead of the unicode character.

• List style

  • Bullet lists: prefer -, *, or +?
    • ehuss's preference: Author's choice.
  • Ordered lists: Prefer 1. or 1)
    • Prefer repeating 1 so you don't have to renumber things? Or prefer to use the numbers 1, 2, 3, ...?
    • ehuss's preference: Author's choice.

• Defining abbreviations

  <abbr title="dynamically sized types">DSTs</abbr>

  These are very helpful to people who may not know all abbreviations.

  Also, I think we should avoid Rust-specific abbreviations if possible (like APIT).

[tshepang]

one very convenient thing Ferrocene docs have is autoglossary (example), so something like DST would automatically have a (faint) underline when it has a glossary entry

[tshepang]

am a fan of - as bullet point, probably because it's more easy to reach on my keyboard (no shift needed), but mostly because it's less noisy

[JoelMarcey]

In the absence of any other suggestions, I am happy to adopt @ehuss's suggestions here as our style guide and update as needed.

[chorman0773]

I think we do need a good way to handle intradoc (clause-id) links, but also links to stdlib docs. Using the same structure as rustdoc for that validation/translation [item] or [name][path] may be reasonable.

I'm not sure that path-based intradoc links will see much use if we can refer to specific clauses (and we should be able to do that). On the other hand, normative and informative references to other docs will require the ability to link to external paths, unless we simply want to use textual citations and provide no direct link to that even when possible.

At the very least, we'd need to be able to cite UAX#31 from Unicode 15.

[ehuss]

I think we do need a good way to handle intradoc (clause-id) links, but also links to stdlib docs.

Sure, I opened #45 to add that support.