Creating good [HowTo]s is frustrating

Feedback Forum
1

Please forgive me. But i am having a hard time in creating an easy to use [HowTo]

1st i asked: Is there a usable offline-Editor with Wysiwyg with the same syntax as the forum ?
Later then i realized that there are a lot of limitations for writing a usable [HowTo]

I would have liked to distinguish between commands the reader has to type, and the results the commands produced on my side as example what to expect.

An simple example:

fsck.ext4 /dev/sdz3

e2fsck 1.46.2 (28-Feb-2021)
/dev/sdz3: sauber, 219881/3891200 Dateien, 1312455/15541243 Blöcke

  • This way i can set the command to bold. But the box does not show a button to copy to the clipboard (with the mouse and CTRL-c you can). And it does not expand if the line is very long. But some commands are long.

  • Then the 2. box does show a button to copy, and it expands if the line is long.

  • But i can’t use bold to mark something. And even worse, it happens to colorize the text in its own way (and not according to shell syntax). Like the numbers in (28-Feb-2021).

or i could have used:

fsck.ext4 /dev/sdz3                                                                                                                                       
e2fsck 1.46.2 (28-Feb-2021)
/dev/sdz3: sauber, 219881/3891200 Dateien, 1312455/15541243 Blöcke
  • This way long lines are possible
  • The copy-symbol is visible
  • But i can’t highlight anything
  • And the system will color the text, but i don’t see how this coloring is useful to understanding. It seems not to respect the syntax of bash.
  • Even worse, when i copy the box, i will get the command, and the results in one block. This is not good for newcomers.

What i expected:

  • A box1 for shell-commands with (narrow) monospace-font, huge length, copy-button and lightly different coloring of the background.
  • A box2 for the results with or without copy button, (narrow) monospace-font, huge length and lightly different coloring from 1. box
  • selectable syntax highlighting like for example in trac so that you can specify wehter the text is
    • none = plain text
    • Shell (bash, zsh, csh)
    • C, C++
    • Java (maybe) :wink:

or even better:

  • A box where 1.line is as box1, and all following lines are of box2. The copy-button would supply only 1.line, but with mouse and CTRL-c you could get also the other text. :smiling_face_with_three_hearts:

Another one:

the command

lsblk

will produce

NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS

…

sdz 8:32 1 59,5G 0 disk
├─sdz1 8:33 1 250M 0 part
├─sdz2 8:34 1 1M 0 part
└─sdz3 8:35 1 59,3G 0 part
sdy 8:48 1 14,7G 0 disk
├─sdy1 8:49 1 250M 0 part
├─sdy2 8:50 1 1M 0 part
└─sdy3 8:51 1 14,5G 0 part

then you have to alter the following commd by replacing z with the letter for your device

ls -lA /dev/disk/by-uuid |egrep ‘z3$’

and you will get

lrwxrwxrwx 1 root root 10 19. Jun 07:58 1a488830-65f7-4913-bf4d-dfe3f3ab5634 -> ../../sdz3

I want to show the reader, that he has to change z3$ in the grep so that the letter z is to be replaced by a letter he found previously in the response to lsblk. Then he has to copy the PARTUUID. But i can’t highlight it.

The best way as i see would be, to highlight the letter z in the response and later on in the command, and to describe to change the yellow part of the command according to the device-name from lsblk

image

image
image856×57 8.4 KB

So the reader would not forget to alter the command accordingly. Then i could describe that he has to watch for the green PARTUUID
But because of the lack of possibilities, i don’ see a way to do this.

Is there a way i don’t recognize ?
Or should i write these parts in libre office, and insert screenshots like i did this time ?

Please be patient. This is not my native language

2

These editors exist, look for markdown editors

It’s markdown builtin, you only need point which language you use:

```java
Some code with java syntax highlighting
```
4 Likes
3

I can’t help at all here, but I wanted to express my thanks to you and anybody else putting so much thought in how to tutorials.

4

discource use markdown, html and bbcode
For languages :

1 Like
5

Thank you this is very good information. :smiling_face_with_three_hearts:

The normal link to markdown does not contain a lot of information, and does not contain links to examples. It looks as somebody had to write a short summary, and then someone did.

May be there is more to dig. Some Programmers do like to implement fancy things, but don’t like to document them afterwards (I am also a programmer :sweat_smile:)

6

exists 36 000 markdown guide on web :wink: like this

EDIT

for command and return, nothing exists
why not 2 “code” in a “quote” ?

[quote]
```journalctl -b0```
#```
juin 20 17:50:33 tower kernel:  #3
#```
[/quote]

result without “#”

1 Like
7

The simple solution:

command to type

output

The complex solution:


Please execute:

```bash
fsck.ext4 /dev/sdz3
```

and that should give you:

```text
e2fsck 1.46.2 (28-Feb-2021)
/dev/sdz3: sauber, 219881/3891200 Dateien, 1312455/15541243 Blöcke
```

:man_shrugging:

1 Like
8

I’m not sure what you find complex and/or confusing here. Give direction, show code. Simple. You’re overthinking this ‘issue’ of yours. You want to actually complexify the editor in my opinion. Your idea of having highlighting withing code blocks and formatting in code blocks is not good to me, again, it is much simpler and clearer to do it simply, examples:

Code:

Do this next action `random code here`

Result:
Do this next action random code here

Code:

Do this next action
```
random code here
and also here again
```

Result:
Do this next action

random code here
and also here again

You can show and tell things easily and clearly, by writing, instead of having multi new features within code blocks

That would be clearer and simpler to have text explanation, then code, instead of what you would like in my opinion. What would make it clearer to have color highlighting (that in itself if just highlighting that people should figure out by themselves) instead of just telling and showing things?

PS: also yeah, Discourse has plenty of documentation for its editor.

//EDIT: few links Discourse New User Guide - faq - Discourse Meta and https://commonmark.org/help/tutorial

1 Like
9

Isn’t that built-in. Please see image below. Item 1 is a toggle that displays or hides the preview. Item 2 expands the composer. Item 3 minimizes the composer.

discourse-edit
discourse-edit1142×400 69.3 KB

See Jeff Atwoods post about what formatting is supported.

Be sure to visit common mark and the 10 minute interactive tutorial.

On the Jeff Atwood post, if you click the “2” a dialog will be displayed where you can view the Raw formatting. That must be a configurable option. At Manjaro I can only do that to my own posts, but at discourse any post. But here, at Manjaro, if you want to see a raw post, to see how someone formated text, you can:

https://forum.manjaro.com/raw/{topicid}/{postid}

https://forum.manjaro.org/raw/71030/1

I hope no one just copies a command from any forum without reviewing it carefully and understanding what it does first. I hope users are also using man documentation. Long lines are hard to read, even if you can scroll. I’d recomment breaking long lines and using line continuation.

In general, imho,

  • keep things simple for yourself
  • concentrate on content
  • be consistent
  • using code (with or without syntax highlighting) and quote blocks will be something users are use to vieiwing
    • use them for their intended (“semantic”) purpose. This is important because Manjaro forum users are using different themes. Plus if there is any type of automation in the future, they may look for the html keywords that are generated based on the markup used.
    • you can specify the language on the code block, which has been recommended above. From reading the discourse forum, highlight.js (not all languages are registered) is used. It looks like officially it is “plain text”, which has aliases of “text” or “txt”. I’ve been using “text”. There is also a “nohighlight” (??), but that skips the block totally (??)

Have fun !

1 Like
10

This Thread is already very helpfull for me (maybe for others too)

It’s more the possibility to copy with a button then visual appearance what i found difficult.

  • There are good constructs that enable the copy-button. And they allow long lines without automatic linebreak, but no markdown.
  • And there are other good constructs that allow markdown or a command to stand out, but they don’t have a copy-button

Or am i missing something ?

1 Like
11

You’re correct and not missing anything! That is by design. There used to be a way around that with <pre><code> HTML tags but that hole was closed over a year ago.

1 Like
12

Also see Tutorial Content Creation Guide

I hope it helps!

13

Indeed, having formatting in the code block (which has the copy button) would defeat the purpose of this specific block which is made to never interpret the code inside… I think it could be relatively not difficult to modify the other block (quote) to have a copy button though but that would mean a change in the forum from admins.

14

There is a syntax highlighter designed for a code block that contains console commands and console output, shell or console. It doesn’t do a whole lot, basically emphasizes the prompt, and I think, uses bash highlighting.

Here is when it was introduced:

GitHub support a “console” keyword that reflect console commands/output.

Example: Shell Session

$
$ echo $EDITOR
vim
$ git checkout main  # this is a comment
Switched to branch 'main'
Your branch is up-to-date with 'origin/main'.
$ git push
Everything up-to-date
$ echo 'All
> done!'
All
done!
$ 
$ declare -p ${!XDG@}

NOTE: The empty prompt (dollar sign) was added to get the syntax highlighting to work :thinking: The highlighting worked on 6/23, but when I revisited on 6/24, it did not. I’m not sure what to make of this, other than when creating content, formatting should be easy :slight_smile:

A language hint can be added at the top and all code blocks will be formatted.


<!-- language-all: console -->
1 Like
15