search

mawww / kakoune

mawww's experiment for a better code editor
http://kakoune.org
The Unlicense
9.7k stars 705 forks source link

[BUG] inconsistent syntax in asciidoc for buffers enclosed by stars such as scratch #5197

Open lobre opened 3 days ago

lobre commented 3 days ago

Version of Kakoune

80fcfebca8c62ace6cf2af9487784486af07d2d5

Reproducer

I manually filtered the output of this command for the below results

$ grep -Er '\\\*|\*debug|\*scratch' **/*.asciidoc

doc/pages/buffers.asciidoc:One particular scratch buffer, named *\*scratch*\*, is automatically created
doc/pages/buffers.asciidoc:A specific *\*debug*\* buffer is used by Kakoune to write errors or
doc/pages/commands.asciidoc:        generated based on format `\*scratch-$ID\*`, where `$ID` is an
doc/pages/commands.asciidoc:        print the given text to the *\*debug** buffer
doc/pages/commands.asciidoc:    print some debug information in the *\*debug** buffer
doc/pages/expansions.asciidoc:Kakoune's `\*debug*` buffer. If you're trying to debug a shell expansion,
doc/pages/expansions.asciidoc:check the debug buffer with `:buffer \*debug*` to see if anything shows up.
doc/pages/faq.asciidoc:Note: `\*col*` is a regular expression that matches your terminal's `$TERM`
doc/pages/faq.asciidoc:state data into the `\*debug*` buffer:
doc/pages/options.asciidoc:    dump various debug information in the '\*debug*' buffer
doc/pages/options.asciidoc:The current values for all options can be dumped to the *\*debug*\* buffer using
README.asciidoc:   ** `-debug`: print the given text to the `\*debug*` buffer

Outcome

When trying to check doc pages to see how those "star-enclosed" *buffers* are highlighted and formatted in the asciidoc syntax, I see different writings.

Here they are:

Sometimes, they are rendered bold, and sometimes as code blocs and there are different syntaxes.

Expectations

Try to come up with a solution that is consistent across the code, and that works for both Kakoune internal rendered docs, and Github rendered docs.

Additional information

No response

arachsys commented 2 days ago

I guess the first is closest to being correct assuming buffer names are meant to be emboldened in the documentation, although it presumably ought to be *\*debug\** not *\*debug*\*, or the final * won't be bold like the first one?