-
Notifications
You must be signed in to change notification settings - Fork 30
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Updates to support writer's guide changes + placeholders nuance #35
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,9 +1,32 @@ | ||
= Code Placeholders | ||
|
||
When you need to add a placeholder value to a xref:examples.adoc[code example]: | ||
The type of placeholder you add to code depends on the type of xref:examples.adoc[code example] you're including. | ||
|
||
== curl and Shell Placeholders | ||
|
||
When you need to add a placeholder value to a curl or other shell code example: | ||
|
||
* Write the placeholder name in capital letters. | ||
* Use a `$` before the placeholder name. | ||
* Use underscores to separate words. | ||
* Use underscores (`_`) to separate words. | ||
|
||
For example, `$DATABASE_NAME`. | ||
|
||
== REST API Path Attribute Placeholders | ||
|
||
When you need to add a placeholder value to a path attribute for a REST API example: | ||
|
||
* Write the placeholder name in capital letters. | ||
* Surround the placeholder name in curly braces (`{}`). | ||
* If necessary, use underscores (`_`) to separate words. | ||
|
||
For example, `{PORT}`. | ||
|
||
== Other Placeholders | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it worth emphasizing that this is the default formatting for placeholders? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't know about "default" - I think I'd rather just leave it as "other" - since we want the other two options to be used where appropriate, first. |
||
|
||
If your code format does not support a value using curly braces (`{}`) or a `$` prefix, then you must: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ...for example, a value in a JSON document,... |
||
|
||
* Write the placeholder name in capital letters. | ||
* Surround the placeholder name in angled brackets (`<>`). | ||
|
||
For example, `$DATABASE_NAME`. | ||
For example, `<YOUR_ATTRIBUTE>`. |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,12 +3,24 @@ | |
Use an unordered or bulleted list when you have a collection of three or more things and the order of the items does not matter. | ||
These items could be nouns, phrases, or topics. | ||
|
||
For example: | ||
|
||
**** | ||
* This is a list item | ||
** This is a sub-item | ||
**** | ||
|
||
If you only have two items in your list, it's okay to just write it out in a sentence. | ||
|
||
Use an unordered list when writing prerequisites or a See Also section in your documentation. | ||
Use an unordered list for prerequisites and the See Also section even if it contains only a single item. | ||
Use an unordered list when: | ||
|
||
* Writing a prerequisites section in your documentation. | ||
* Writing a See Also section in your documentation. | ||
* Structuring the `nav.adoc` file in a documentation module. | ||
|
||
NOTE: Use an unordered list for prerequisites and the See Also section even if it contains only a single item. | ||
|
||
Use an asterix (*) to render an item as an unordered list item. | ||
Use an asterix (`*`) to render an item as an unordered list item. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. asterisk (throughout) |
||
The number of asterixes sets the depth of the list item. | ||
|
||
For more information about how to format an unordered list in Antora, see xref:home:contribute:basics.adoc#unordered-lists[Unordered Lists] in the Contributing to the Documentation guide. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cURL
(throughout)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was surprised to find out recently that they've renamed cURL to curl.
Had to change it in a few places in the docs.