Re: [Docutils-users] How to add index information

[Guenter M. <mi...@us...>]

On 2020-08-28, Alan Williamson wrote:

> Thanks, I do have to admit to being very new to all if this!  Let me
> restate what I am trying to do which might make it clearer.

>   1.  I know Sphinx does not provide the text indexing I want, and the
>       maintainers have no interest in doing that.

May be one of the many Sphinx extensions is close to what you want.
(I have to admit, that I don't know much about Sphinx extensions, though.)

>   2.  I want to download the reStructuredText for the GitHub repository
>       (done)

Do you mean:

* documentation of some GitHub project in the form of rST source files,

* code used by GitHub to process rST documents,

* something else?

>   3.  I want to ‘tag’ various words in the text so that those tags can
>       be used by my MadCap Flare documentation system to generate its
>       index (I have code to convert the tagged reST files to the XHTML
>       that Flare requires)

I expect that some "keywords" should be wrapped in e.g. ::

   <span class="include-in-index">parrot</span>.
   
in a HTML rendering of the rST source.   

>   4.  The tagged rest files end up back in the GitHib repository so
>       that the tags are persistent as the online developers make
>       changes to the online documentation.

>   5.  As an example if I have “this is ProductX information” as text
>       and want to use ‘ProductX’ as an index term, then I added the
>       html comments as follows::
>
>           this is <!—start -->ProductX<!—end >--> information
>   6.  My Flare import routines consume the start/end constructs and
>       create what’s needed.

Is this particular way of tagging required by your routines or would
other markup work as well?

>   7.  When the rest files are put back into the GitHub repository the
>       intention was that they would be ‘just html comments that are
>       ignored’

> So that all worked – except for 7 – the tagging appears following the
> Sphinx/ReadTheDocs process.

rST is not Markup. The "<" and ">" characters have no special meaning in
rST so the parser sees your "comments" as normal text.

> I don’t understand your comments re ‘raw’ html, so I will start to read
> further.

In order to embed HTML parts into rST, you need to use special markup ---
the "raw" role https://docutils.sourceforge.io/docs/ref/rst/roles.html#raw :

  The "raw" role cannot be used directly. The "role" directive must first
  be used to build custom roles based on the "raw" role. One or more
  formats (Writer names) must be provided in a "format" option.

  For example, the following creates an HTML-specific "raw-html" role:

  .. role:: raw-html(raw)
     :format: html

  This role can now be used directly to pass data untouched to the HTML
  Writer. For example::
  
    If there just *has* to be a line break here,
    :raw-html:`<br />`
    it can be accomplished with a "raw"-derived role.
    But the line block syntax should be considered first.

So, a "role" based on "raw" *can* be used for your purpose, but it is
probably not the best choice. You have to create a custom role in any case.

> I had read about custom roles so that is of real interest, however I
> got a little lost – I do want to live within the existing framework.  

This depends on how much editing of the rST source files is
tolerated/supported by the other developers of the project.

Example:

Define a custom role, in the rST source file (before first use),
https://docutils.sourceforge.io/docs/ref/rst/directives.html#role
e.g.::

  .. role:: MadCap-keyword
  
Now you can use this role to tag your keywords::

  this is :MadCap-keyword:`ProductX` information
  
and the docutils HTML writer (or Sphinx) will generate the following HTML::

  <p>this is <span class="madcap-keyword">ProductX</span> information</p>
  
which is looks as before (unless you style it with CSS).

Günter