Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Hi,
My documentation refers to services that use user-specified labels, but the services have attributes so I need to show the possessive. Let me introduce the problem gradually: Suppose I start with a sentence like: Compare the configuration for `A` and `B`.This renders as: Compare the configuration for A and B .
If I change the sentence to: Compare `A`'s and `B`'s configuration.This renders as: Compare `A’s and `B’s configuration. The single quote processing has broken the monospace processing. So then I try: Compare ``A``'s and ``B``'s configuration.Which renders as: Compare A 's and B 's configuration.
Since I'd like to use typographer's apostrophes, I next try: Compare ``A```'s and ``B```'s configuration.This renders as expected: Compare A ’s and B ’s configuration.
But, not if the sentence is more complete: Compare ``A```'s and ``B```'s configuration after running `*some command*`.this renders as: Compare A's and B’s configuration after running `some command .
I'm curious if there's a way to markup these scenarios so that the monospace and typographer's apostrophes can be achieved in a consistent manner, regardless of markup elsewhere in the sentence/paragraph? Thanks! |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
This is just one of those quirks of AsciiDoc / Asciidoctor that isn't going to be easily resolved until we switch to using a proper inline parser. The current approach is very context blind. What often seems obvious to a human is not obvious at all to the parser. A grammar can help address the problem because it can work from the outside in. My general recommendation in the meantime is to either use inline passthroughs (an incredibly useful tool), like: ---- Compare pass:q[`A`]`'s and pass:q[`B`]`'s configuration after running ``*some command*``. ---- or use attributes: ---- :varA: pass:q[`A`] :varB: pass:q[`B`] Compare {varA}`'s and {varB}`'s configuration after running `*some command*`. ---- The second approach is most robust than the first...notice it doesn't require double backticks around "some command". The final approach is just to use typographic quotes in the source, which is how I write. It's also the most robust. ---- Compare `A`’s and `B`’s configuration after running `*some command*`. ---- I know these are not necessarily ideal (or even pretty) solutions, but there's simply no way to get the parser to do this right until we change how we parse. We know we have to take this step and we will. -Dan On Fri, Sep 25, 2015 at 5:24 PM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi, ... [show rest of quote] Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
In reply to this post by eskwayrd
Btw, learning to type typographic quotes (and accented characters) is probably the best thing you can do to add proficiency to your writing. You'll find other ways to use the Compose key other than typographic quotes and you'll start to benefit from these shorthand strokes in no time. I think the best AsciiDoc is AsciiDoc that avoids using substitution for things like typographic quotes, dashes and the like and just puts the character directly into the document. There's already enough formatting in AsciiDoc that you don't need to overload it with all these replacement shortcuts when you can just type the real thing. -Dan On Sat, Sep 26, 2015 at 3:16 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
In reply to this post by eskwayrd
...of course, the replacements are very convenient for new writers...so I'm not suggesting we get rid of them. But I do expect experience writers to graduate from using these training wheels and type the character you want in the document. -Dan On Sat, Sep 26, 2015 at 3:19 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
In reply to this post by mojavelinux
Do you have a sense for how far along this kind of improvement in AsciiDoc(tor) might be? Passthroughs are very useful. Given the number of labels our documentation uses, I think passthroughs are the way to go; there's no dependency on definition or inclusion, and it's easier when the examples that use the labels need updating. I'm converting our documentation from DocBook to AsciiDoc, and I've scripted the bulk of the work. All of our <command> tags (when they don't contain <replaceable> tags) get converted into double backticks already. Thanks very much! Your thoughtful and reasoned support is one of the reasons we're converting to AsciiDoc! |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
On Mon, Sep 28, 2015 at 7:44 AM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote: Do you have a sense for how far along this kind of improvement in AsciiDoc(tor) might be? At the moment, no. It highly depends on whether I can get enough funding to start working on it full (or even half time). It's a task that is going to take a lot of focus and I need to make sure I don't run out of food trying :) With that said, I'm constantly thinking about the design changes in my head and mapping out what we're going to need to do to get there. |
Free forum by Nabble | Edit this page |