Repository navigation
SOLR-18494: Document one block style for commands in the Ref Guide - #5006
serhiy-bzhezytskyy wants to merge 8 commits into
Conversation
The authoring guide only said to use text when in doubt, while most command blocks use bash and others console, so new pages kept mixing styles. Spell out which style a block of commands, commands with output, and output alone get.
github-actions
Bot
added
the
documentation
| @@ -88,6 +88,28 @@ Use one of the valid short names to get syntax highlighting for that language. | |||
|
|
|||
| Ideally, we will have an appropriate lexer to use for all source blocks, but that's not possible. | |||
There was a problem hiding this comment.
why is this not possible? Has antora/asciidoc not expanded to cover everything? Not sure this blanket statement is still true. Maybe?
There was a problem hiding this comment.
That sentence was written for Rouge, but the published Guide is highlighted by highlight.js, so I corrected the section (ceb5ba9). And "not possible" is almost no longer true: 22 of the 2,478 blocks with a language use a name the highlighter lacks (powershell 8, terminal 6, bat 4, and one each r, promql, csv, subs); the rest are highlighted.
epugh
left a comment
epugh
left a comment
There was a problem hiding this comment.
LGTM. One thing I tried a while ago was to make the "copy" command in the Ref Guide work. I think in antora you could have a copy icon so you would get just the command without the $, but I didn't have any luck with it. It would sort of work. Might be worth a quick check to see if that feature works better now.
|
Let's leave this PR open a few more days, see if we get any other feedback on it? |
The authoring guide named Rouge and its lexer list, but the published pages use the highlight.js build of the UI bundle, which has 35 languages. The section now names those, says what happens to any other name, and notes that powershell is not among them yet.
|
Is this PR done then? If it's only documentation? Or, are you also in this PR fixing the various styles? (Or did the get done elsewhere).... |
…uide The list would go stale with the first change to the UI bundle; the section now says that the bundle decides which languages are highlighted and what happens to any other name.
|
Checked the script behind the copy button in the Guide's UI bundle: on a |
A reader who copies a block should get the commands and nothing else. A block with commands only is now `bash` without a prompt, a block with commands and their output is `console` with `$`, and output alone is `text`; the Windows variants stay `powershell`.
|
Not only documentation: cd7108c applies the rule to the pages, 192 command blocks in 26 files. |
…tton The copy button takes only the `$` lines of a console block, so a command with a multi-line argument would be copied as its first line.
|
thanks, I think I was seeing just a single commit fo rsome reason, and was suprised there were more files changed! testing now! |
| The `--version` command simply returns the version of Solr currently installed and immediately exists. | ||
|
|
||
| [source,bash] | ||
| [source,console] |
There was a problem hiding this comment.
should this be source,console? I guess I don't see a single pattern of when we sue bash and when we use console?
There was a problem hiding this comment.
Already console at dac8b99: it shows the output (X.Y.0) under the $ line. The rule in dev-docs/ref-guide/asciidoc-syntax.adoc (lines 97-99): commands plus output use console with $, commands only use bash with no prompt.
| First export the documents, making sure to ignore any fields that are populated via a `copyField` by specifying what fields you want to export: | ||
|
|
||
| [,console] | ||
| [,bash] |
There was a problem hiding this comment.
Already bash at dac8b99: commands only, no prompt, so the copy button copies the block as is.
2 participants
https://issues.apache.org/jira/browse/SOLR-18494
Description
Command blocks in the Ref Guide use several styles: of 624 blocks holding a
curlorbin/solrcommand on main, 473 arebash, 123 areconsoleand 28 usetext,plain,terminal,sh,powershellor no language. The authoring guide says only "when in doubt, choosetext".Solution
Adds a "Command Blocks" section to
dev-docs/ref-guide/asciidoc-syntax.adoc:bashwithout a prompt for commands only,consolewith$when the output is shown too,textfor output alone,powershellfor the Windows variant. The pages themselves are not touched; they can follow once the rule is agreed.Written with Claude Code.
Tests
The page renders and the new cross-reference resolves. The example command and output are copied from
tutorial-films.adoc.Checklist
mainbranch../gradlew check.