bonsai/harakit
4
4
Fork 3
Code Issues 39 Pull Requests 3 Projects 1 Releases 36 Activity

rtfm(1) - manual pages #41

New Issue
Open
opened 2024-02-02 23:22:50 -07:00 by emma · 9 comments
emma commented 2024-02-02 23:22:50 -07:00
Owner
Copy Link

https://commonmark.org/

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
Author
Owner
Copy Link

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
Owner
Copy Link

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
Author
Owner
Copy Link

I think comments should probably be ;;

I think comments should probably be `;;`
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 2024-03-01 06:41:21 -07:00
Owner
Copy Link

Another point against roff is that it can run arbitrary commands.

Another point against roff is that it can [run arbitrary commands](https://news.ycombinator.com/item?id=39554085).
emma commented 2024-07-07 19:18:15 -06:00
Author
Owner
Copy Link

@trinity mentioned renaming this to the more interesting rtfm(1).

@trinity mentioned renaming this to the more interesting `rtfm(1)`.
emma changed title from `doc(1)` - manual pages in commonmark to `rtfm(1)` - manual pages in commonmark 2024-07-15 14:16:08 -06:00
emma changed title from `rtfm(1)` - manual pages in commonmark to `rtfm(1)` - manual pages 2024-07-15 14:16:15 -06:00
sashakoshka commented 2024-12-16 17:06:40 -07:00
Copy Link

In my opinion, it would be a good idea to make this two programs, rtfm and a text formatter, where the former calls upon the latter. This would enable other programs to make use of this language.

In my opinion, it would be a good idea to make this two programs, rtfm and a text formatter, where the former calls upon the latter. This would enable other programs to make use of this language.
emma commented 2025-01-30 00:22:43 -07:00
Author
Owner
Copy Link

In my opinion, it would be a good idea to make this two programs, rtfm and a text formatter, where the former calls upon the latter.

I agree.

> In my opinion, it would be a good idea to make this two programs, rtfm and a text formatter, where the former calls upon the latter. I agree.
trinity commented 2025-03-21 15:02:32 -06:00
Owner
Copy Link

rtfm(1)'s function would be database management; the "find" in find | format | page. Ideally it could be a shell script.

rtfm(1)'s function would be database management; the "find" in find | format | page. Ideally it could be a shell script.
emma commented 2025-03-24 19:26:21 -06:00
Author
Owner
Copy Link

rtfm(1)'s function would be database management; the "find" in find | format | page. Ideally it could be a shell script.

Agreed.

> rtfm(1)'s function would be database management; the "find" in find | format | page. Ideally it could be a shell script. Agreed.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Something is not working
duplicate
This issue or pull request already exists
enhancement
New feature
help wanted
Need some help
invalid
Something is wrong
joke
you are silly!
question
More information is needed
wontfix
This won't be fixed
No Label
enhancement
help wanted
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
emma nitori silt trinity
No Assignees emma
3 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: bonsai/harakit#41
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?