Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Append .md suffix to text docs. Adjust references. #36

Merged
merged 12 commits into from
Jun 11, 2020
Merged

Append .md suffix to text docs. Adjust references. #36

merged 12 commits into from
Jun 11, 2020

Conversation

schmonz
Copy link
Member

@schmonz schmonz commented Jul 19, 2019 •
edited
Loading

Rationale, in some sort of order:

  • Plain text is already valid Markdown (and we can improve it as we go)
  • Markdown is already plain text, readable in all the same ways
  • GitHub also renders Markdown nicely in web browsers
  • Changing installed names for docs is a non-zero compatibility break,
    but we consider it small enough to tolerate:
    1. Programs are unaffected
    2. People will press <tab> and find what they're seeking

Supports goals: Being easily packaged by OS integrators
Broaches non-goals: Breaking compatibility (but tolerably so)
Risks: Users won't find needed info; patches to hier.c may get skewed

@schmonz schmonz added this to the 1.07 milestone Jul 19, 2019
@alanpost
Copy link
Contributor

For files like INSTALL.mds, which you have renamed to INSTALL.mds.md, what do you think about replacing the first (original) period (.) with a dash (-)? INSTALL.mds.md visually looks like INSTALL.tar.gz, in that you expect this to be an .md .mds file, whereas using a dash more idiomatically states this is the -mds section of the INSTALL notes.

alanpost
alanpost reviewed Jul 19, 2019
View reviewed changes
SYSDEPS.md Outdated Show resolved Hide resolved
alanpost
alanpost reviewed Jul 19, 2019
View reviewed changes
install-big.c Outdated Show resolved Hide resolved
@schmonz
Copy link
Member Author

schmonz commented Jul 20, 2019

Renaming a little more, so we have INSTALL-foo.md instead of INSTALL.foo.md: I'm open to the idea. If you're reading this, what do you prefer?

@alanpost alanpost modified the milestones: 1.07, 1.08 Jul 20, 2019
@alanpost alanpost mentioned this pull request Jul 20, 2019
Merged
@alanpost alanpost added the documentation Improvements or additions to documentation label Jul 23, 2019
@alanpost alanpost mentioned this pull request Jul 23, 2019
Open
@alanpost alanpost mentioned this pull request Aug 6, 2019
Closed
@schmonz schmonz force-pushed the doc-file-extensions branch 2 times, most recently from cd93379 to 9cc1c08 Compare May 23, 2020 14:02
@DerDakon
Copy link
Member

I would spare 2 files from this:

  • COPYRIGHT, as that may where e.g. GitHub as well as other tools automatically look for. I guess most will look for copyright* case insensitive, but still.
  • TARGETS: it's just an internal file of the buildsystem, and it's also where the .gitignore file is symlinked to. Making this markdown gives no benefits as it's just a list of files.

@schmonz schmonz force-pushed the doc-file-extensions branch 4 times, most recently from 5b06f21 to eaf8e72 Compare May 23, 2020 15:42
josuah
josuah approved these changes May 24, 2020
View reviewed changes
Copy link

@josuah josuah left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Files can be further renamed from INSTALL.alias.md to INSTALL-alias.md later if wanted.

INTERNALS.md Show resolved Hide resolved
@schmonz
Append .md suffix to text docs. Adjust references.
9746afb 
Rationale, in some sort of order:

- Plain text is already valid Markdown (and we can improve it as we go)
- Markdown is already plain text, readable in all the same ways
- GitHub also renders Markdown nicely in web browsers
- Changing installed names for docs is a non-zero compatibility break,
  but we consider it small enough to tolerate:
    1. Programs are unaffected
    2. People will press <tab> and find what they're seeking

Supports goals: Being easily packaged by OS integrators
Broaches non-goals: Breaking compatibility (but tolerably so)
Risks: Users won't find needed info; patches to hier.c may get skewed
@schmonz
Improve README Markdown.
2e86dab
@schmonz schmonz merged commit b39f9ca into master Jun 11, 2020
@schmonz schmonz deleted the doc-file-extensions branch June 11, 2020 13:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@josuah josuah josuah approved these changes

@DerDakon DerDakon DerDakon approved these changes

@leahneukirchen leahneukirchen leahneukirchen approved these changes

@alanpost alanpost Awaiting requested review from alanpost

@jlmuir jlmuir Awaiting requested review from jlmuir

@mbhangui mbhangui Awaiting requested review from mbhangui

@xenotrope xenotrope Awaiting requested review from xenotrope

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
1.09
Development

Successfully merging this pull request may close these issues.
5 participants
@schmonz @alanpost @DerDakon @leahneukirchen @josuah