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

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

On 2020-08-30, Alan Williamson wrote:

> Hello Günter,

> I believe your custom role suggestion is what I need, however just a
> comment or two re your advice.

>>   2.  I want to download the reStructuredText for the GitHub repository
> * documentation of some GitHub project in the form of rST source files,

>>   6.  My Flare import routines consume the start/end constructs and
>>       create what’s needed.
...
> I can use almost anything that can be parsed.

>>   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’
> rST is not Markup. The "<" and ">" characters have no special meaning in
> rST so the parser sees your "comments" as normal text.

> Yes, understood, I just thought if it passes the <!—and --> text
> through to the parser it would be ignored, but apparently not.

Have a look at the HTML that gets generated from "the <!—and --> text"
in the rST source: HTML-special characters are escaped intentionally!

> If I understand correctly, if I used ‘raw’ I would need to have the
> role defined near the beginning of each .rst as follows:

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

> and then ‘tag’ my index word as “This section describes
> :raw.html:`<!—ProductX -->`productX in detail.” As you say, and as I
> have read, “raw” is considered a stop-gap and would not be the best
> choice.

Yes.

> I believe that a custom role would be acceptable to the team.  As I
> begin the process of indexing I would add the definition, and they
> would happily ignore the tagging I add.  They might even decide to help
> with indexing if they thought it important!

> Tomorrow begins a new week here in Australia so I will have them try
> it.  At the beginning of one .rst file we have: “The permissions
> associated with SureDrop user roles are: “, so we will have the
> definition and insertion as::

>   .. role::MadCap-index

>   The :MadCap-index:`Permissions` permissions associated with SureDrop
>   user roles are:

> Here I assume using ‘index’ instead of ‘keyword’ is OK

Any "normal" role name will work.  You should check with the project
developers, maybe it is better to use just ``index``, maybe you should
prepend a "namespace tag".

> , and that I am
> able to define another custom role such as .. role:MadCap-condition
> that I can use to tag text as conditionally included/excluded depending
> on whether a MadCap condition is true or false. 

Have a look at the `strip-elements-with-classes`_ configuration setting!

https://docutils.sourceforge.io/docs/user/config.html#strip-elements-with-classes


Günter