rtfm(1) - manual pages #41

New Issue

emma · 2024-02-02T23:22:50-07:00

emma commented

2024-02-02 23:22:50 -07:00

https://commonmark.org/

emma added the

enhancement

label 2024-02-02 23:22:50 -07:00

emma self-assigned this 2024-02-02 23:22:50 -07:00

emma commented

2024-02-03 13:57:42 -07:00

I’ve decided on a strict subset of commonmark to implement for this:

Italics: *Italics*
Bold: __Bold__
Heading: # Heading 1 (will be used for section number), ## Heading 2 (for all other headings)
Link: [Text][Ref] and at the bottom of the doc [Ref] http://example.com
List: - List item
Numbered List: 1. Numbered item
Code: three backticks to open/close blocks and one backtick to open and close inline code
Quote Block: > Quote Block

plus a couple of extensions:
Underline: _Underline_
Strikethrough: ~Strikethrough~
Comments: ; Comment

I’ve decided on a strict subset of commonmark to implement for this: - Italics: `*Italics*` - Bold: `__Bold__` - Heading: `# Heading 1` (will be used for section number),` ## Heading 2` (for all other headings) - Link: `[Text][Ref]` and at the bottom of the doc `[Ref] http://example.com` - List: `- List item` - Numbered List: `1. Numbered item` - Code: three backticks to open/close blocks and one backtick to open and close inline code - Quote Block: `> Quote Block` plus a couple of extensions: Underline: `_Underline_` Strikethrough: `~Strikethrough~` Comments: `; Comment`

trinity commented

2024-02-03 21:25:49 -07:00

Could # headers be specifically for title/section metadata?

For example, roff:

.TH  PAGE 1

and my proposed equivalent usage in doc:

# PAGE(1)

Or PAGE 1 or whatever would be best. Just an idea. It would also be nice to have ### - just in general it may be handy but also in particular with # being title specification.

I think the following would be more consistent: **bold**, __underline__, ~~strikethrough~~, //italic//. All of these are flanked by two of the same rune on either side, which helps writers remember them easier.

And then potentially if they're useful (or even theoretically so) ~~\\diminished\\ (e.g. <small /> in obsolete HTML, or like whispers in comic books)~~ (edit: backslashes as markup is a bad idea), ^^superscript^^, ,,subscript,,, but I'm not in love with any of these, they're just ideas I thought up.

It would be nice to have in-line references, maybe similarly to MediaWiki. I don't wanna scroll down to find the hyperlink for a reference and then have to find my previous position.

; is a fine comment character. I'm a little wary of common punctuation but starting a line with a semicolon is unusual and nonsensical so it's probably fine. If it initiates a comment at any point in a line though and not at the start that could be a big problem.

Could `#` headers be specifically for title/section metadata? For example, roff: ``` .TH PAGE 1 ``` and my proposed equivalent usage in doc: ``` # PAGE(1) ``` Or `PAGE 1` or whatever would be best. Just an idea. It would also be nice to have `###` - just in general it may be handy but also in particular with `#` being title specification. I think the following would be more consistent: `**bold**`, `__underline__`, `~~strikethrough~~`, `//italic//`. All of these are flanked by two of the same rune on either side, which helps writers remember them easier. And then potentially if they're useful (or even theoretically so) ~~`\\diminished\\` (e.g. `<small />` in obsolete HTML, or like whispers in comic books)~~ (**edit: backslashes as markup is a bad idea**), `^^superscript^^`, `,,subscript,,`, but I'm not in love with any of these, they're just ideas I thought up. It would be nice to have in-line references, maybe similarly to MediaWiki. I don't wanna scroll down to find the hyperlink for a reference and then have to find my previous position. `;` is a fine comment character. I'm a little wary of common punctuation but starting a line with a semicolon is unusual and nonsensical so it's probably fine. If it initiates a comment at any point in a line though and not at the start that could be a big problem.

emma commented

2024-02-06 22:27:17 -07:00

I think comments should probably be ;;

I think comments should probably be `;;`

trinity closed this issue

2024-02-06 22:42:20 -07:00

emma reopened this issue

2024-02-06 22:59:26 -07:00

emma added the

help wanted

label 2024-02-07 20:25:55 -07:00

trinity commented