docutils-users

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

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

Hi Günter

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.
  2.  I want to download the reStructuredText for the GitHub repository (done)
  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)
  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 and 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.
  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.

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

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

Alan

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

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.

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