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

[Alan W. <ala...@li...>]

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
>       (done)
I meant:

* 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.
Is this particular way of tagging required by your routines or would
other markup work as well?

I can use almost anything that can be parsed.  My import routines are written in c#

>   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.

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.

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, 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. For example I might want to include text in a novices user guide:

  <p>:MadCap-condition:`Novice`">This is text  that is included for novices.:MadCap-condition:`end’</p>

My import routines would extract “Novice” and use it to build the MadCap conditional expression and apply it to the text up to the trailing MadCap-condition that contained the reserved ‘end’ condition.  Of course I have no control over what is included in the Sphinx/ReadTheDocs output, but I sometimes do need to include/exclude their text and this will let me do that.

Thanks again, I will repost when I have the results.

Alan




_______________________________________________
Docutils-users mailing list
Doc...@li...
https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.sourceforge.net%2Flists%2Flistinfo%2Fdocutils-users&amp;data=02%7C01%7C%7Cff763a0ba5224a58b77808d84c136693%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637342993505936273&amp;sdata=iZHOzu18CqtVOHDZgxKl25I3jrIhHryjqpZv9J%2FunSM%3D&amp;reserved=0

Please use "Reply All" to reply to the list.