Codeberg/Documentation
42
199
Fork
You've already forked Documentation
161

Improve email settings article #215

Merged
n merged 3 commits from ka2in/Documentation:main into main 2022年04月17日 06:03:43 +02:00
Contributor
Copy link

Edit and review of the article about email settings

Edit and review of the article about email settings
Reviewed-on: ka2in/Documentation#1 
Reviewed-on: ka2in/Documentation#2 
Reviewed-on: ka2in/Documentation#3
Contributor
Copy link

I guess this is related to #153.

I guess this is related to #153.
Author
Contributor
Copy link

@jklippel: Yes, I reviewed your contribution and made some minor changes.

@jklippel: Yes, I reviewed your contribution and made some minor changes.
@ -15,2 +13,3 @@
To change your notification preferences, go to your [user settings](https://codeberg.org/user/settings/account) or manually navigate to the settings.
In the section "Manage Email Addresses" you can select from one of the following options for each Email address that you registered with Codeberg:
You can access the settings by clicking on the menu button “Profile and Settings...” in the top-right corner. From there, navigate to Settings > Account > Manage Email Addresses.
Contributor
Copy link

Why not just use double quotes directly?

Why not just use double quotes directly?
Author
Contributor
Copy link
  1. Please check the following article about straight vs. curly quotes in typography: https://practicaltypography.com/straight-and-curly-quotes.html
  2. I am also following the conventions of the GNU community based on my past experience with their localization team:
    https://www.gnu.org/server/standards/gnu-website-guidelines.en.html

Besides, using HTML entities consistently helps to avoid any possible rendering issues.

1. Please check the following article about straight vs. curly quotes in typography: https://practicaltypography.com/straight-and-curly-quotes.html 2. I am also following the conventions of the GNU community based on my past experience with their localization team: https://www.gnu.org/server/standards/gnu-website-guidelines.en.html Besides, using HTML entities consistently helps to avoid any possible rendering issues.
Contributor
Copy link

While the guidance you've linked might make sense for HTML documents, I don't think it would be appropriate to use HTML entities in our markdown documents if not absolutely necessary.

I think markdown-it — the markdown renderer we use — has an option for replacing straight quotes with curly quotes wherever relevant.

While the guidance you've linked might make sense for HTML documents, I don't think it would be appropriate to use HTML entities in our markdown documents if not absolutely necessary. I think `markdown-it` — the markdown renderer we use — has an option for replacing straight quotes with curly quotes wherever relevant.
Contributor
Copy link

Anyways, for this PR, let's use straight quotes. The curly quote config for markdown-it can be discussed and added in another issue/PR.

Anyways, for this PR, let's use straight quotes. The curly quote config for `markdown-it` can be discussed and added in another issue/PR.
Author
Contributor
Copy link

@n Thank you for the comment. Using straight quotes is not best practice in typography. If you check the first article that I suggested, you can read the following:

"Straight quotes are a typewriter habit. In traditional printing, all quotation marks were curly. But typewriter character sets were limited by mechanical constraints and physical space. By replacing the curly opening and closing quotes with ambidextrous straight quotes, two slots became available for other characters."

"Compared to straight quotes, curly quotes are more legible on the page and match the other characters better. Therefore, straight quotes should never, ever appear in your documents."

It seems to me that markdown-it, the markdown renderer you use, is not aware of this typographical rule.

@n Thank you for the comment. Using straight quotes is not best practice in typography. If you check the first article that I suggested, you can read the following: “Straight quotes are a typewriter habit. In traditional printing, all quotation marks were curly. But typewriter character sets were limited by mechanical constraints and physical space. By replacing the curly opening and closing quotes with ambidextrous straight quotes, two slots became available for other characters.” “Compared to straight quotes, curly quotes are more legible on the page and match the other characters better. Therefore, straight quotes should never, ever appear in your documents.“ It seems to me that `markdown-it`, the markdown renderer you use, is not aware of this typographical rule.
Author
Contributor
Copy link

@n I've just added a style guide for documentation contributors right now. There is a section for the appropriate use of quotes, too.

@n I've just added a style guide for documentation contributors right now. There is a section for the appropriate use of quotes, too.
@ -25,2 +25,3 @@
Press the button “Set Email Preference” to confirm your selection.
Note that disabling Email notifications will not disable receiving important communication from the Codeberg organisation.
> **Note:**<br />disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation.
Contributor
Copy link

Let's stick to markdown wherever we can.

-> **Note:**<br />disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation.
+> **Note:** 
+> disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation.
Let's stick to markdown wherever we can. ```diff -> **Note:**<br />disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation. +> **Note:** +> disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation. ```
Author
Contributor
Copy link

Good point. Thank you for the feedback! 👍

Good point. Thank you for the feedback! 👍
fnetX marked this conversation as resolved
n changed title from (削除) main (削除ここまで) to Improve email settings article 2022年04月10日 13:56:26 +02:00
fnetX added the due date 2022年04月17日 2022年04月14日 12:35:24 +02:00
Contributor
Copy link

Multipart answer, parts numbered for easier reference:

(1) @ka2in: Could you please put the style guide into a separate pull request. It is a separate issue (#216) and it should be discussed apart from the resolution of #215.

(2) Apart from that I think that the Markdown files should be readable by anyone with a text editor in the un-rendered form. Introducing html markup for the quotations and the single tick character is in my opinion contraproductive here. Maybe we should try to convince upstream (markdown-it) (by raising issue and providing pull requests) to (optionally) allow the rendering of the quotes in the way favoured by you.

(3) I think that the styleguide is important and Codeberg should have one. But it should not be merged based on the oppinion of a handful of people. This should somehow be discussed in a broader circle. How can we proceed with this? (ping @fnetX: any idea?) (Btw, this is one more reason to split it into a different PR.)

Multipart answer, parts numbered for easier reference: (1) @ka2in: Could you please put the style guide into a separate pull request. It is a separate issue (#216) and it should be discussed apart from the resolution of #215. (2) Apart from that I think that the Markdown files should be readable by anyone with a text editor in the un-rendered form. Introducing html markup for the quotations and the single tick character is in my opinion contraproductive here. Maybe we should try to convince upstream (markdown-it) (by raising issue and providing pull requests) to (optionally) allow the rendering of the quotes in the way favoured by you. (3) I think that the styleguide is important and Codeberg should have one. But it should not be merged based on the oppinion of a handful of people. This should somehow be discussed in a broader circle. How can we proceed with this? (ping @fnetX: any idea?) (Btw, this is one more reason to split it into a different PR.)
Owner
Copy link

I object to using HTML entities in markdown.

Can't we just insert the quotes as is? „" etc? Shouldn't this be enough given that the HTML should be delivered in Unicode, too?

I object to using HTML entities in markdown. Can't we just insert the quotes as is? „" etc? Shouldn't this be enough given that the HTML should be delivered in Unicode, too?
Author
Contributor
Copy link

@fnetX Yes, inserting the quotes directly should be enough. It does not matter how we achieve to use quotes properly.

@fnetX Yes, inserting the quotes directly should be enough. It does not matter how we achieve to use quotes properly.
Author
Contributor
Copy link

@jklippel
(1) Done.
(2) Agree.
(3) The proposed style guide is a starting point. Feel free to adjust, extend, and modify according to the community's needs.

@jklippel (1) Done. (2) Agree. (3) The proposed style guide is a starting point. Feel free to adjust, extend, and modify according to the community's needs.
n approved these changes 2022年04月17日 06:03:27 +02:00
n left a comment
Copy link

Thank you!

Thank you!
Sign in to join this conversation.
No reviewers
n
Labels
Clear labels
Codeberg Pages
Issues affecting Codeberg Pages
Documentation Usability
Issues related to using and reading docs.codeberg.org
Forgejo
Good First Issue! 👋
Kind: Bug
Kind: Documentation
Kind: Enhancement
Kind: Feature
Kind: Question
Kind: Security
Licensing
Part: Generator
This is related to the generation of the documentation, not to the content itself
Priority: High
The priority is high
Priority: Low
The priority is low
Priority: Medium
The priority is medium
Reviewed: Confirmed
Something has been confirmed
Reviewed: Duplicate
Something exists already
Reviewed: Invalid
Something was marked as invalid
Reviewed: Wontfix
Something won't be fixed
Status: Blocked
Status: Help wanted
Contributions are welcome!
Status: In progress
Work is in progress
Status: Needs feedback
Feedback is needed
Status: Ready for Review
Work is completed
Status: Review
Review is in progress / Reviewers wanted
Status: Stale
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
4 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

2022年04月17日

Dependencies

No dependencies set.

Reference
Codeberg/Documentation!215
Reference in a new issue
Codeberg/Documentation
No description provided.
Delete branch "ka2in/Documentation:main"

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?