How to markup typographer's quotes for monospaced labels?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

How to markup typographer's quotes for monospaced labels?

eskwayrd
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!
Reply | Threaded
Open this post in threaded view
|

Re: How to markup typographer's quotes for monospaced labels?

mojavelinux
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,
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!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-markup-typographer-s-quotes-for-monospaced-labels-tp3754.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: How to markup typographer's quotes for monospaced labels?

mojavelinux
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:
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,
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!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-markup-typographer-s-quotes-for-monospaced-labels-tp3754.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: How to markup typographer's quotes for monospaced labels?

mojavelinux
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:
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:
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,
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!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-markup-typographer-s-quotes-for-monospaced-labels-tp3754.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: How to markup typographer's quotes for monospaced labels?

eskwayrd
In reply to this post by mojavelinux
mojavelinux wrote
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.
Do you have a sense for how far along this kind of improvement in AsciiDoc(tor) might be?

mojavelinux wrote
My general recommendation in the meantime is to either use inline
passthroughs (an incredibly useful tool), like:
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.


mojavelinux wrote
The second approach is most robust than the first...notice it doesn't
require double backticks around "some command".
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.

mojavelinux wrote
The final approach is just to use typographic quotes in the source, which
is how I write. It's also the most robust.
Thanks very much! Your thoughtful and reasoned support is one of the reasons we're converting to AsciiDoc!
Reply | Threaded
Open this post in threaded view
|

Re: How to markup typographer's quotes for monospaced labels?

mojavelinux
Administrator

On Mon, Sep 28, 2015 at 7:44 AM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
mojavelinux wrote
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.
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.

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen