Italics within inline monospace?

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

Italics within inline monospace?

eskwayrd
Hi,

I'm busy converting a bunch of DocBook technical documentation to AsciiDoc (using AsciiDoctor as part of the transformation to HTML/PDF). We have many command-line examples where we like to express user-selectable inputs with <replaceable>. A contrived example: <command>cat <replaceable>filename</replaceable></command>.

Converting the example into AsciiDoc: `cat _filename_`

Results in:
HTML: <p><code>cat _filename_</code></p>
DocBook: <simpara><literal>cat _filename_</literal></simpara>

Asciidoctor.js (via AsciiDoctor FX) renders this more correctly as:

cat <EM xmlns="http://www.w3.org/1999/xhtml">filename</EM>

If my source is changed to: ``cat _filename_``, I get:

HTML: <p>``cat <em>filename</em>``</p>
DocBook: <simpara>``cat <emphasis>filename</emphasis>``</simpara>
Asciidoctor FX: cat <EM xmlns="http://www.w3.org/1999/xhtml">filename</EM>

What's the best/correct way to achieve italics within inline monospace?
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

eskwayrd
And a follow-on question:

If I relinquish inline monospace, I can achieve expected results with:

[source,bash,subs="normal"]
cat _filename_

Which renders as:

HTML: <pre class="highlight"><code class="bash language-bash">cat <em>filename</em></code></pre>
DocBook: <programlisting language="bash" linenumbering="unnumbered">cat <emphasis>filename</emphasis></programlisting>

So far, so good. However, single quotes turn into emphasis; with source like:

[source,bash,subs="normal"]
echo '_text_'

I get:
HTML: <pre class="highlight"><code class="bash language-bash">echo <em><em>text</em></em></code></pre>
DocBook: <programlisting language="bash" linenumbering="unnumbered">echo <emphasis><emphasis>text</emphasis></emphasis></programlisting>

Suggestions?
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator
In reply to this post by eskwayrd

On Tue, Jun 16, 2015 at 2:54 PM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
What's the best/correct way to achieve italics within inline monospace?

You had it right the first time if you are using Asciidoctor tooling.

`cat _filename_`

This works differently in AsciiDoc Python for reasons explained here: http://asciidoctor.org/docs/migration/

If you want it to work in both Asciidoctor and AsciiDoc Python, you either need to type it as:

+cat _filename_+

and enable the compat-mode attribute, or you can type it as:

[x-]`cat _filename_`

without the compat-mode attribute.

You can think of [x-] as a local compat mode setting.

Cheers,

Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator
In reply to this post by eskwayrd

On Tue, Jun 16, 2015 at 3:08 PM, Dan Allen <[hidden email]> wrote:
or you can type it as:

[x-]`cat _filename_`

without the compat-mode attribute.

Oops! I meant to type:

[x-]+cat _filename_+

I've added this as an example in the migration guide for reference.

Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

eskwayrd
Hi,

[x-]+cat _filename_+

Solves my first problem nicely! BTW: I am using AsciiDoctor, and `cat _filename_` does not work.

This technique is no panacea, through. Suppose I were trying to describe the Unix date command, applying emphasis appropriately, I would try this:

[x-]+date [-jnu] [[[_mm_]_dd_]_HH_]_MM_[[_cc_]_yy_][._ss_]+

That causes '[_mm_]' and ['_cc_'] to be processed as paragraph styles. If I escape any of the open square brackets, they are no longer character classes, but then 'mm' and 'cc' are not emphasized. Escaping all of the open square brackets renders with many backslashes included.

Similarly, other characters defeat the emphasis I'd like to apply:

[x-]+echo '_HH_:_MM_:_SS_'+

Renders in DocBook as:

<simpara><literal><phrase role="x-">echo <emphasis><emphasis>HH</emphasis>:_MM_:_SS_</emphasis></phrase></literal></simpara>

I can avoid having the single quotes from being handled as emphasis with:

[x-]+echo \'_HH_:_MM_:_SS_'+

but that implies massaging each existing command example to apply the escapement properly, as escaping both single quotes causes the backslash to appear in front of the second single quote.

Any further suggestions?
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator

On Wed, Jun 17, 2015 at 12:09 PM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
[x-]+date [-jnu] [[[_mm_]_dd_]_HH_]_MM_[[_cc_]_yy_][._ss_]+

My reaction to seeing this is that you are stretching AsciiDoc too far. For one, I wouldn't be able to make sense of this as an editor, so I think it takes away from the goal of “easy to read, easy to edit”.

This is where extensions shine, in my opinion. You should apply some semantic tag to the command and then use an extension point to parse and format the command at a lower level. Something like:

[command]
date [-jun] [[[mm]dd]HH] MM [[cc]yy][.ss]

Then you can intercept the content in the extension, parse it however you like an emit the result in DocBook or HTML, depending on the current backend.

I suggest this because it encourages the separation of content and presentation. All that formatting in the command is not content.

Having said that, once we switch to a proper parser for inline formatting, then Asciidoctor will be able to do better at making sense of a lot of nested formatting. See https://github.com/asciidoctor/asciidoctor/issues/61

Cheers,

-Dan
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator
In reply to this post by eskwayrd

On Wed, Jun 17, 2015 at 12:09 PM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
and `cat _filename_` does not work.

It depends on which version of Asciidoctor you are using and what the compat-mode setting is....and also how you define "work" :)

It will produce the following if you use Asciidoctor 1.5.x and compat-mode is not defined:

<div class="paragraph">
<p><code>cat <em>filename</em></code></p>
</div>

-Dan
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator
In reply to this post by eskwayrd

On Wed, Jun 17, 2015 at 12:09 PM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
but that implies massaging each existing command example to apply the escapement properly, as escaping both single quotes causes the backslash to appear in front of the second single quote.

That's how AsciiDoc works. Formatting common symbols is one of the hardest things to do in AsciiDoc because those symbols have meaning in the syntax. In general, I recommend avoiding the manual formatting of any more than just a handful of symbols.

Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator
In reply to this post by eskwayrd
I was thinking more about this and I realized that what you are actually doing is syntax highlighting the code....it's just that the code is a command.

What you might want to consider is creating a scanner for CodeRay {1}. Then, you can do something like:

[source,command]
date [-jun] [[[mm]dd]HH] MM [[cc]yy][.ss]

And then you'll get the callback in CodeRay to handle this and syntax highlight it. That way, it will work in both Asciidoctor and Asciidoctor PDF. And, of course, the result will be in monospaced text because it's a source block.

Cheers,

-Dan


On Wed, Jun 17, 2015 at 12:25 PM, Dan Allen <[hidden email]> wrote:

On Wed, Jun 17, 2015 at 12:09 PM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
but that implies massaging each existing command example to apply the escapement properly, as escaping both single quotes causes the backslash to appear in front of the second single quote.

That's how AsciiDoc works. Formatting common symbols is one of the hardest things to do in AsciiDoc because those symbols have meaning in the syntax. In general, I recommend avoiding the manual formatting of any more than just a handful of symbols.




--
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

eskwayrd
In reply to this post by mojavelinux
mojavelinux wrote
My reaction to seeing this is that you are stretching AsciiDoc too far. For
one, I wouldn't be able to make sense of this as an editor, so I think it
takes away from the goal of “easy to read, easy to edit”.
Indeed. However, we are documenting the syntax of a wide set of commands; there is no "easy". Using AsciiDoctor is deemed easier than having our authors use DocBook for the bulk of our guides, but command examples are very important and need to be correctly formatted.

mojavelinux wrote
Then you can intercept the content in the extension, parse it however you
like an emit the result in DocBook or HTML, depending on the current
backend.

I suggest this because it encourages the separation of content and
presentation. All that formatting in the command is not content.
I agree that separation of content and presentation is important. However, pushing all of the semantics into a separate parser takes control away from the documentation author, and represents a maintenance burden; when the command syntax evolves, the parser must too because all knowledge of which arguments to a command require arbitrary data, versus a selection from a static list must be embedded. For us, it's certainly not as straightforward as syntax highlighting.

While we're not actually documenting a command like 'date', it does represent some of the argument complexity of the commands we do include in our documentation. DocBook provides ample semantic control when tackling these sorts of markup scenarios. For example, the date command would be unambiguously expressed in DocBook as:

<command>date [-jnu] [[[<replaceable>mm</replaceable>]<replaceable>dd</replaceable>]<replaceable>HH</replaceable>]<replaceable>MM</replaceable>[[<replaceable>cc</replaceable>]<replaceable>yy</replaceable>][.<replaceable>ss</replaceable>]</command>

I expect passthrough inlines/blocks is the immediate solution; that will guarantee that the several thousand command examples we currently document continue to appear as expected in our published guides, and that any new command/argument coverage can be attempted in AsciiDoc with a fallback to DocBook when necessary.

mojavelinux wrote
Having said that, once we switch to a proper parser for inline formatting,
then Asciidoctor will be able to do better at making sense of a lot of
nested formatting. See https://github.com/asciidoctor/asciidoctor/issues/61
I look forward to the new inline parser.

Thanks very much for the suggestions and thoughtful responses!
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

jnilo
In reply to this post by mojavelinux
mojavelinux wrote
Oops! I meant to type:

[x-]+cat _filename_+
This works great to insure asciidoc & asciidoctor html compatibility. But I have a problem when trying to generate a  pdf using a2x. I have the following single line test.adoc file
This is [x-]+cat _filename_+
Which is translated into the following xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<?asciidoc-toc?>
<?asciidoc-numbered?>

<article lang="en">
<articleinfo>
    <date>2015-07-02</date>
</articleinfo>
<simpara>This is <literal><phrase role="x-">cat <emphasis>filename</emphasis></phrase></literal></simpara>
</article>
But when I issue a2x -f pdf -v test.adoc I get the following error
a2x: executing: "xmllint" --nonet --noout --valid "/home/Jacques/Documentation/test/test.xml"

/home/Jacques/Documentation/test/test.xml:10: element literal: validity error : Element phrase is not declared in literal list of possible children
 <literal><phrase role="x-">cat <emphasis>filename</emphasis></phrase></literal>
                                                                               ^
a2x: ERROR: "xmllint" --nonet --noout --valid "/home/Pascal/Documentation/test/test.xml" returned non-zero exit status 4
Can someone tell me where the problem lies ?
J.
Reply | Threaded
Open this post in threaded view
|

Re: Italics within inline monospace?

mojavelinux
Administrator

On Wed, Jul 1, 2015 at 11:37 PM, jnilo [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I have a problem when trying to generate a  pdf using a2x.

In this case, you should use Asciidoctor to convert to DocBook, then use a2x to convert from DocBook onwards.

-Dan

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

Re: Italics within inline monospace?

mojavelinux
Administrator
In reply to this post by eskwayrd

On Thu, Jun 18, 2015 at 8:51 AM, eskwayrd [via Asciidoctor :: Discussion] <[hidden email]> wrote:
For example, the date command would be unambiguously expressed in DocBook as:

<command>date [-jnu] [[[<replaceable>mm</replaceable>]<replaceable>dd</replaceable>]<replaceable>HH</replaceable>]<replaceable>MM</replaceable>[[<replaceable>cc</replaceable>]<replaceable>yy</replaceable>][.<replaceable>ss</replaceable>]</command>

I expect passthrough inlines/blocks is the immediate solution;

+1 In this case, that seems the most reasonable solution. DocBook is actually more readable (albeit verbose) than AsciiDoc in this particular scenario.

The other option here would be to introduce a DSL for describing these commands. In the end, you accomplish the same thing, but perhaps you can cut down on the number of characters that have to be typed.

Of course, you'd need to design and maintain that DSL, but it would probably make the authors quiet happy. In fact, there may even be such a DSL that already exists. Something like Clops. http://clops.sourceforge.net/ That would make a killer extension for Asciidoctor.

The beauty of AsciiDoc is that you aren't stuck with just AsciiDoc. That's what extension are for. But you should aim to maintain the separation of content and presentation.

Cheers,

-Dan


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