docutils-users Mailing List for Docutils: Documentation Utilities

On 2/18/2018 4:45 PM, Guenter Milde via Docutils-users wrote:
> The separate div is the HTML4-compatible representation of the section
> element (with the HTML5 writer this will eventually become a <section>
> element, too).

Yea! (Although by "too" I hope you mean "instead".)
Please announce when you do this.
Cheers,
Alan

On Tue, Feb 27, 2018 at 11:53 AM, Gary Mamon <ga...@ia...> wrote:
> * How can I make a many-character non-POSIX (i.e. single dash signs) option
> list, i.e.
>
> -data file # data filename
>
> OR
>
> -data file -> data filename

You cannot, per the reStructuredText Markup Specification:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists

The 4 types of option markup allowed are:

* Short POSIX
* Long POSIX
* Old GNU-style "plus"
* DOS/VMS "slash"

> where the first data is highlighted as a literal, the “file” is highlighted
> as emphasis (italics), and the tabulation between “file” and “#” or “->” is
> a real tab so that subsequent lines are vertically aligned?

Note: tabs are not used. Tables or other markup are used.

> Using standard option lists doesn’t work:
> 1) multiple-character options have their first letter in literal and the
> next ones in emphasis, which is weird.

Not weird once you understand what's going on. A line like:

    -option    description

is simply interpreted as the short POSIX option "-o" followed by the
argument "ption" and a description.

Trying to mix single-dash long options with short options is ambiguous
at best, and not supported by reStructuredText.

> 2) some lines with arguments fail to process correctly.

See the spec for correct syntax. Non-POSIX styles are not supported though.

> * As an alternative, I could enclose all lines in a literal block. But then,
> how can I place emphasis on some of the words within the literal block?

You could use a parsed literal block:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

> * A 3rd possibility is do the mark-up word by word. But then, how can I
> insert tabs to enforce vertical alignment?

Again, there are no tabs. You could use a table.

David Goodger
<http://python.net/~goodger>

* How can I make a many-character non-POSIX (i.e. single dash signs) option list, i.e.

-data file	# data filename

OR

-data file	-> data filename

where the first data is highlighted as a literal, the “file” is highlighted as emphasis (italics), and the tabulation between “file” and “#” or “->” is a real tab so that subsequent lines are vertically aligned?

Using standard option lists doesn’t work: 
1) multiple-character options have their first letter in literal and the next ones in emphasis, which is weird. 
2) some lines with arguments fail to process correctly.

* As an alternative, I could enclose all lines in a literal block. But then, how can I place emphasis on some of the words within the literal block?

* A 3rd possibility is do the mark-up word by word. But then, how can I insert tabs to enforce vertical alignment?

	thanks in advance

	Gary Mamon

On 2018-02-14, Ciro Santilli wrote:

> Please CC.

This doesn't work with slrn via GMANE, sorry.

> Cross post:
> https://stackoverflow.com/questions/48759542/how-to-create-and-reference-custom-heading-ids-with-restructuredtext

> Currently, if I have:

>     My header
>     =========

>     `My header`_
 
> `rst2html` Docutils 0.14 produces:

>     <div class="document" id="my-header">
>     <h1 class="title">My header</h1>

>     <p><a class="reference internal" href="#my-header">My header</a></p>

> Is it possible to obtain the following ouptut instead:

>     <h1 class="title" id="my-custom-header">My header</h1>

>     <p><a class="reference internal" href="#my-custom-header">My
> header</a></p>

Not easily, but see below.

> So note how I want two changes:

> - the id to be inside the heading, not on a separate div

The separate div is the HTML4-compatible representation of the section
element (with the HTML5 writer this will eventually become a <section>
element, too). With Docutils, the id is given to the <section>, not the
section's <title>.

> - control over the actual id

In Docutils, an element can have multiple ids but for the HTML
representation these need to be put on separate elements.
The current mechanism works for most practical purposes -- you may create a
custom HTML writer or propose a patch (and good resons for a change) to have
the custom id replacing the auto-generated one.

> The closest I could get was:

>     <div class="document" id="my-header">
>     <span id="my-custom-header"></span>
>     <h1 class="title">My header</h1>

>     <p><a class="reference external" href="my-custom-header">My
> header</a></p>

> but this is still not ideal, as I now have multiple ids floating around,
> and not inside the `h1`.

> Asciidoc for example has that covered with:

>     [[my-custom-header]]
>     == My header

>     <<my-custom-header>>

Well, the input is quite similar to the rST you probably used to get the
"close version"::


    .. _my custom header:
    
    My header
    =========
  
    `my custom header`_

This is translated to the internal representation::

  <document source="/tmp/foo.rst">
      <target refid="my-custom-header"></target>
      <section ids="my-header my-custom-header" 
               names="my\ header my\ custom\ header">
          <title>My header</title>
          <paragraph><reference name="my custom header"
                                refid="my-custom-header">my custom
                     header</reference></paragraph>
      </section>
  </document>

So everything is there to get the desired HTML output via a custom writer.
But is it worth the effort?


Günter

   

Please CC.

Cross post:
https://stackoverflow.com/questions/48759542/how-to-create-and-reference-custom-heading-ids-with-restructuredtext

Currently, if I have:

    My header
    =========

    `My header`_

`rst2html` Docutils 0.14 produces:

    <div class="document" id="my-header">
    <h1 class="title">My header</h1>

    <p><a class="reference internal" href="#my-header">My header</a></p>

Is it possible to obtain the following ouptut instead:

    <h1 class="title" id="my-custom-header">My header</h1>

    <p><a class="reference internal" href="#my-custom-header">My
header</a></p>

So note how I want two changes:

- the id to be inside the heading, not on a separate div
- control over the actual id

The closest I could get was:

    <div class="document" id="my-header">
    <span id="my-custom-header"></span>
    <h1 class="title">My header</h1>

    <p><a class="reference external" href="my-custom-header">My
header</a></p>

but this is still not ideal, as I now have multiple ids floating around,
and not inside the `h1`.

Asciidoc for example has that covered with:

    [[my-custom-header]]
    == My header

    <<my-custom-header>>