Comments (9)
Keyboard shortcuts - kbd:[key1(+key2+...)].
Yep, true. This needs to be added. => #8
At the same time, this only works if you set :experimental: in the master file
Other recommended mark-up in these guidelines also requires that. For some reason, the doc doesn't mention this even though I'm pretty sure it used to. Needs fixing. => #9
Admonitions - [NOTE], [IMPORTANT], [WARNING]. Those are used all the time and very useful. They don't need any special parameters, but the document should explain to people when to use each admonition
This doc doesn't want to teach people how to write properly. This is purely about styling of various elements. As admonitions (AFAIK) cannot be marked-up/styled in any other way, there's no reason to talk about them (here).
Tables - there's no mention of those. It's not a huge problem since it's basically just "do an asciidoc table"
Exactly.
however other elements that are just basic adoc, like links or images, are explained in the doc so we should cover tables too
Links and images can be marked-up in a number of ways (various parameters can be specified), so we want to standardize on one way (what is the minimum that should be defined).
Come to think of it, this may be true for tables, too. Should be investigated. => #10
The ADoc equivalent of xrefs, so we can point to internal IDs and get autogenerated links.
I believe this is standard mark-up (<<id>>
or xref:id
), so no reason to include it.
"Code blocks" could use a link to a list of languages supported by the highlighter
Good point. => #11
"Command blocks" a link to the ADoc reference explaining [subs=...] options, or better yet, just list useful options and what they do.
Again, the aim is not to teach people to use adoc. That said, a link (above or below the table) to adoc reference and user manual wouldn't hurt. => #12
We should also mention that yes, please add the prompt (# or $ based on whether the user is expected to be root or not), and don't add the current directory (foo]#).
This request isn't about mark-up/style but about best practices for writing. So, these guidelines are not the right place for it. That said, this is one of the issues we have identified that should be standardized. The team has agreed to take it up next and possibly add such recommendations to the doc published by the Documentation Conventions initiative.
from asciidoc-markup-conventions.
Hey,
I will add the line to the document and make a pull request.
Lukas
from asciidoc-markup-conventions.
@rkratky I mostly agree, just one more thing about admonitions: even if we don't explain when to use each one, how about at least noting that the syntax is a bit different from other blocks (e.g. code) in that admonitions are delimited by ====
instead of ....
or ----
?
from asciidoc-markup-conventions.
Will this markup build an admonition?
[NOTE]
....
Note?
....
Let me test it.
from asciidoc-markup-conventions.
@pbokoc , @rkratky
So, the only possible mark-up for admonitions is:
[ADMONITION]
====
Something
====
Do we have to explicitly say that other delimiters will not work? We are saying to use the correct version already. I do not think we need any more explanation on that. Or?
from asciidoc-markup-conventions.
@pbokoc, I understand there's a potential for confusion, but there are many such areas. I wouldn't want this doc to slide towards "AsciiDoc help". If people use incorrect syntax (for anything, incl. admonitions), well, it happens. It's not the aim of this doc to teach people how to use adoc.
from asciidoc-markup-conventions.
@rkratky Re "not the aim of this doc to teach people how to use adoc."
Linking to the asciidoctor.org/docs/user-manual in Additional Resources is nice. Unfortunately, it does not mention the needs for + in +quotes. How about a "Known Issues" section at the bottom as a compromise?
from asciidoc-markup-conventions.
How about a "Known Issues" section at the bottom as a compromise?
+1
from asciidoc-markup-conventions.
Let me know if this is best raised in a new issue now, but I want to add some support to this point suggested by pbokoc:
- The ADoc equivalent of xrefs, so we can point to internal IDs and get autogenerated links.
While I agree that this is not the place to teach people to use AsciiDoc, I've searched through all of the 'Additional Resources' listed, and I don't see a place that clearly explains that leaving the square brackets empty after xrefs will automatically pull in the title that follows that ID, even if it changes, and why that can be useful. We've seen a few maintenance issues caused by folks thinking they needed to manually include a section title in their xref.
Internally, on the documentation teams I work with, we've provided the following example in a team document:
See xref:configuring_a_database[] (leave the square brackets blank to ensure that the title is pulled directly from the topic)
I think similar guidance would be useful and more visible in the Quick Reference.
If the consensus is not to be that prescriptive about xref usage, we could also include another example for comparison, like this:
See xref:configuring_a_database[this section]
from asciidoc-markup-conventions.
Related Issues (20)
- Add supported syntax highlighting formats HOT 2
- Add links to AsciiDoc(tor) user manual and mark-up reference HOT 1
- Add intro paragraph HOT 2
- Edit text to say 'Click' instead of 'Press' HOT 1
- Mark the conventions that are experimental HOT 3
- Add 'Inline Icons' to this list
- Fix link to mod docs guide
- nbsp for product names HOT 4
- Use of Italics for "System or software variable to be replaced by the user" HOT 8
- Product name
- the subtitle is not accurate HOT 2
- Incorrect example of emphasis for a term HOT 3
- Keyboard shortcut example doesn't match IBM Style HOT 1
- Double underscore for italics surrounded by chevrons (aka pointy brackets)
- {nbsp} in Command Block HOT 1
- Needs to be more robust HOT 5
- Update the 'Reference to Red Hat guides' example HOT 1
- Update the 'System or software variable to be replaced by the user' example ad markup used HOT 1
- Update the 'Anchor' example HOT 3
- Add context description to clarify purpose of this resource
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from asciidoc-markup-conventions.