fedora-docs / release-notes

Clone
Source Code
GIT

#735 Present reader with smart apostrophes
Opened 3 years ago by jayman. Modified 3 years ago
fedora-docs/ jayman/release-notes smart-apostrophes  into  master

Merge
file modified
+6 -6 
@@ -1,7 +1,7 @@ 
 

  # Fedora Release Notes
 

  

  Please report Issues and submit Pull Requests for **Content Fixes** here.
 

- Never done a pull request (or "PR")? Here's the [Pagure documentation for
 

+ Never done a pull request (or "PR")? Here’s the [Pagure documentation for
 

  Pull Requests](https://docs.pagure.org/pagure/usage/pull_requests.html).
 

  

  
@@ -45,7 +45,7 @@ 
 

  Antora introduces two new terms:
 

  

  * **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Poject, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity.
 

- * **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
 

+ * **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that’s what is in this example). If you don’t want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
 

  

  ## Local preview
 

  
@@ -65,7 +65,7 @@ 
 

  

  ### Installing Podman on Fedora
 

  

- Fedora Workstation doesn't come with Podman preinstalled by default — so you might need to install it using the following command:
 

+ Fedora Workstation doesn’t come with Podman preinstalled by default — so you might need to install it using the following command:
 

  

  ```
 

  $ sudo dnf install podman
 
@@ -86,7 +86,7 @@ 
 

  $ cd docs-fp-o
 

  ```
 

  

- Find a reference to the repository you're changing in the `site.yml` file, and change it so it points to your change.
 

+ Find a reference to the repository you’re changing in the `site.yml` file, and change it so it points to your change.
 

  So for example, if I made a modification to the Modularity docs, I would find:
 

  

  ```
 
@@ -106,9 +106,9 @@ 
 

  ...
 

  ```
 

  

- I could also point to a local repository, using `HEAD` as a branch to preview the what's changed without the need of making a commit.
 

+ I could also point to a local repository, using `HEAD` as a branch to preview the what’s changed without the need of making a commit.
 

  

- **Note:** I would need to move the repository under the `docs-fp-o` directory, because the builder won't see anything above.
 

+ **Note:** I would need to move the repository under the `docs-fp-o` directory, because the builder won’t see anything above.
 

  So I would need to create a `repositories` directory in `docs-fp-o` and copy my repository into it.
 

  

  ```

Originally, this repo would sometimes present the reader with U+0027
APOSTROPHE for apostrophes and sometimes present the reader with U+2019
RIGHT SINGLE QUOTATION MARK for apostrophes. This change makes it use
U+2019 because that’s what Unicode recommends.

See:

Hmmm. You're correct, but I'm not sure if I want to accept this PR.

Here's the problem: Even if you fix all the apostrophes here, with every subsequent release as people fill in more relnotes beats, they will keep using U+2019, because it's just so much easier to write on an English keyboard. That's going to lead to a mix U+0027 in the parts that carry over between releases, and U+2019 in parts specific to each release, and it's going to look worse than using U+2019 everywhere. We would have to constantly watch every PR and tell people to fix their quotes, and that would be a ton of extra work with the gains not justifying the effort. What do you think, @jayman?
Edited 3 years ago by pbokoc

Here's the problem: Even if you fix all the apostrophes here, with every subsequent release as people fill in more relnotes beats, they will keep using U+2019, because it's just so much easier to write on an English keyboard.

I think you flipped it here. U+0027 is the one that’s on most English keyboards. That being said, using the numbers is confusing. I’m going to start calling U+0027s ASCII Apostrophes and start calling U+2019s Right Single Quotes.

That's going to lead to a mix U+0027 in the parts that carry over between releases, and U+2019 in parts specific to each release, and it's going to look worse than using U+2019 everywhere. We would have to constantly watch every PR and tell people to fix their quotes, and that would be a ton of extra work with the gains not justifying the effort. What do you think, @jayman?

I almost agree, but there’s a few key details that make me disagree. First, we already have a mix of ASCII Apostrophes and Right Single Quotes. This repository exclusively contains ASCII Apostrophes, but when the source files get rendered to HTML, most of them end up using Right Single Quotes. ASCII Apostrophes are automatically replaced in AsciiDoc files but not in Markdown files.

For example, modules/release-notes/pages/welcome/Welcome.adoc says

The Fedora Project's mission is to lead the advancement of free and open source software and content as a collaborative community.

using an ASCII Apostrophe. The rendered version of that file says

The Fedora Project’s mission is to lead the advancement of free and open source software and content as a collaborative community.

using a Right Single Quote.

Second, the only Markdown file in this repo is README.md. If the goal is to always include Right Single Quotes when the files are rendered, then the only file that has to be messed with is README.md. README.md doesn’t include any information that’s specific to each release.

In conclusion, I don’t think that it would be a ton of extra work. That being said, it still might not be worth the effort.
Metadata
None
No Tags
Changes Summary 1
+6 -6
file changed
README.md
Powered by Pagure 5.14.1
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.