Fix highlighting of source code blocks throughout the Atomic Desktops docs site #11
hricky
Loading…
Add table
Add a link
Reference in a new issue
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?
As much as possible and where it makes sense, we should remove the
$signs from the code snippets where we expect users will copy/paste the commands as is.We should make sure to use the
consolecode style for the cases where we have a$and thebashcode style where we don't have one.Imported from https://pagure.io/fedora-kde/kinoite-docs/issue/15
@siosm wrote in #11 (comment):
As far as I know, our Fedora (and also Red Hat) guides do not recommend this, but rather what is already our established current style, see:
https://docs.fedoraproject.org/en-US/atomic-desktops/contributing/#writing-documentation
https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/#_typographic_style_guide
https://stylepedia.net/style/#documenting-command-syntax
@siosm wrote in #11 (comment):
We already do this, except in cases where it degrades the visual layout of the commands and their output.
I'm fine either way.
@hricky wrote in #11 (comment):
I just realized that I overlooked the source highlighting for code blocks and instead of
[source,console]we are currently mostly using[source]or[source,bash]. So when I copy the source code block to the clipboard, the$is also copied. This is an unpleasant user experience and I will fix it throughout the Atomic Desktops docs site.Remove dollar sign '$' from the terminal commandsto Fix highlighting of source code blocks throughout the Atomic Desktops docs siteIf you just use
[,console], it produces a block where if the user highlights a line, the$or#at the start won't be highlighted, so you can copypaste lines easily. You can see an example here:Output: https://docs.fedoraproject.org/en-US/epel/getting-started/#_el10
Source: https://forge.fedoraproject.org/epel/docs/src/branch/main/modules/ROOT/pages/getting-started.adoc?display=source#L35
Oh this is nice. Let's do that.
@siosm wrote in #11 (comment):
If you don't mind, I would prefer the longer and more descriptive form (
[source,console]) that I mentioned in my previous comment. I tested it and the rendering of the HTML site is identical for both forms. For reference, see https://docs.asciidoctor.org/asciidoc/latest/verbatim/source-highlighter/#shell-vs-console.Ah, sure, I did not know that both were equivalent. Usually better to be explicit.
So I guess a lot of the "code" blocks only need an update from bash to console.
Yes, I fixed a few files in different commits and when I'm done with the rest, I'll open a PR with all of them.
Apparently the
source-highlighterattribute with theconsolesource language used treats#as the start of a comment. When the line begins with it, the entire line is not even copied to the clipboard. This actually makes sense, as it is an expected and nice feature. However, it kind of contradicts with the writing style conventions/gudes referred in one of my previous post.The Typographic style guide in the Fedora Documentation Style Guide states:
The Command Terminology and Syntax section of the Red Hat Technical Writing Style Guide states at the beginning:
And also below:
...some sections omitted...
So, should we replace the
#symbol at the beginning of lines with the$ sudoprompt/command, contrary to conventions/guides, or should we disable thesource-highlighterattribute with theconsolesource language used, and continue to provide the not-so-pleasant user experience of copying$and#to the clipboard?Or maybe something different?
Well, we already don't follow the recommendations from https://docs.fedoraproject.org/en-US/atomic-desktops/contributing/#writing-documentation in https://docs.fedoraproject.org/en-US/atomic-desktops/tips-and-tricks/#_hiding_the_default_browser_firefox for example.
I think we should remove those recommendations and instead rely on the general docs recommendations if they exists?
But in the meantime I'm leaning towards using
$ sudoeverywhere as that's what we are using already.I think the general docs recommendations should be The Command Terminology and Syntax section of the Red Hat Technical Writing Style Guide, which as mentioned begins with:
Since the specifics of Antora/AsciiDoc and their copy/paste functionalities are not covered in this document and for a better user experience, I also think it would be better to replace the
#symbol at the beginning of lines with the$ sudoprompt/command.@hricky The bit from the Red Hat Technical Writing Style Guide isn't all that relevant in this particular case (it's a good resource otherwise, though a bit too expansive for community use).
In Red Hat Enterprise Linux, there's typically a root account on the machine that can be normally accessed, and procedures in docs often tell the user to start by switching to root. This avoids having to put "sudo" on every line. In that case, the prompt is useful to remind the user "where" they are. So, if you're in the middle of a procedure, the next step shows the
$prompt and you're seeing a#or the other way around, it's a good idea to take a second look because you probably missed a step, or you're looking at the wrong terminal session.Fedora has had locked down root by default for years now, so everything is done through sudo, and the distinction becomes less important, the prompt is pretty much always going to be a
$. We could even drop it completely, but sometimes it's useful to indicate a difference between a command and its output. So, as @siosm says, I'd use$ sudoeverywhere.Sometimes it is convenient to use
sudo -ito avoid typingsudofor subsequent commands. Currently in Fedora Silverblue this changes both the colour and the symbol of the prompt. Anyhow, it doesn't seem to matter that much and I'll follow your suggestions and use$ sudoeverywhere.