docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

On 06/12/2020 20:34, Alan G. Isaac wrote:
> Why copy/paste at all when you can just ``include`` code?

Thanks, that is a good idea for longer code Alan!

My case is different. For example in one document I have about 50 code 
blocks, which are about 2 to 8 lines long. Creating 50 files for this 
purpose would be very inconvenient.

When I copy code from the rendered version then it's no problem, but 
copying from the rst source is very error-prone due to the indentation, 
e.g.,:

code:: sh

   cat > file <<EOF
     4spaces here instead of 2
   and EOF does not work
   EOF

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Alan G. I. <ala...@gm...>]

Why copy/paste at all when you can just ``include`` code?
Alan Isaac (who is just another user)


On 12/5/2020 5:15 AM, Gökçe Aydos wrote:
> I use rst heavily for my documents and slides for teaching which in turn include many code blocks. Is it possible to use code blocks in rst without indenting 
> them, e.g., like *fenced code blocks*?
> 
> The reason is, it is cumbersome to copy and paste indented code blocks. There is an extension for Sphinx for this purpose [1]. Is there a plan to integrate 
> fenced code blocks in rst?

Re: [Docutils-users] RST margin right question

[engelbert g. <eng...@gm...>]

On Sun, 6 Dec 2020 at 07:30, John Yara <len...@gm...> wrote:

> Hi
>
> I did a lot of research but i did not find anything useful.
> I have an issue when i write in a file.rst something like that.
>
> ::
>
>    Paragraph 1
>
>
> When i convert it into pdf with rst2pdf we can see that the paragraph have
> margin left and right around 2cm.
> I would like to know if it's possible to change the margin-right to have
> only 1cm. ?
>
> Sorry for my english.
>

thanks for the question.

margins are not part of "text" but the "view", "indentation" is "markup" in
rST (and python)
the view depends on styleshhets in html, sty-les in latex
assuming you use rst2pdf from pypi there are stylesheets too
see https://rst2pdf.org/static/manual.pdf

all the best

> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

I use rst heavily for my documents and slides for teaching which in turn 
include many code blocks. Is it possible to use code blocks in rst 
without indenting them, e.g., like *fenced code blocks*?

The reason is, it is cumbersome to copy and paste indented code blocks. 
There is an extension for Sphinx for this purpose [1]. Is there a plan 
to integrate fenced code blocks in rst?

I am not subscribed and would be happy if you could CC me.

[1] https://sphinx-codefence.readthedocs.io/

[Docutils-users] alternative heading syntax

[Danil S. <shk...@gm...>]

Hello.

Do you mind telling please if there is a way to alternate the way headings
are marked up?

My biggest issues with the current style are that
It is uncomfortable to text search for all heading lines since the syntax
makes them at least 2 lines
and I have to change the size of underline when I change the text.

Would be nice if I could just use some substitution or a directive or a
role.
But I do not seem to find anything sufficient in the documentation.
And I do not want to modify or extend docutils.

Apart from that the specification suits my ideas of beauty and simplicity.

Thank you.

Someone's older discussion.
https://sourceforge.net/p/docutils/mailman/message/30356904/

[Docutils-users] RST margin right question

[John Y. <len...@gm...>]

Hi

I did a lot of research but i did not find anything useful.
I have an issue when i write in a file.rst something like that.

::

   Paragraph 1


When i convert it into pdf with rst2pdf we can see that the paragraph have
margin left and right around 2cm.
I would like to know if it's possible to change the margin-right to have
only 1cm. ?

Sorry for my english.

Re: [Docutils-users] Additional List of TOC generated when publishing from doctree

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

On 2020-11-30, Thomas Krug via Docutils-users wrote:

> Hi there,

> I'm using docutils to generate latex which works great.
> But I stumbled upon a problem with TOC generation.

> If I use publish_string() the generated tex is correct.
> If I use publish_doctree() then publish_from_doctree() the generated tex
> contains an additional list containing the TOC.

Thank you for the report and example. This was actually a bug in the latex
writer - not ignoring the Docutils-generated ToC with use-latex-toc.

(The "Contents" transform skips the generation when the "use-latex-toc"
setting is True, but this setting is unknown when generating the doctree
with publish_doctree().)

This is now fixed in the repository (r8582).

Thanks again
Günter

[Docutils-users] Additional List of TOC generated when publishing from doctree

[Thomas K. <t....@tu...>]

Hi there,

I'm using docutils to generate latex which works great.
But I stumbled upon a problem with TOC generation.

If I use publish_string() the generated tex is correct.
If I use publish_doctree() then publish_from_doctree() the generated tex
contains an additional list containing the TOC.

I'm not sure if I'm missing something here.

I attached a minimal working example and the diff of the generated tex
files.

Greetings,
Thomas

[Docutils-users] Docutils Markdown parser (was: Is reStructuredText required for conversion to HTML)

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

Dear Cris, Omer, and everybody,

On 2020-09-23, chris sewell wrote:
> On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users
> <doc...@li...> wrote:
> > On 2020-09-23, Omer Shommo wrote:

> > > I am new to docutils. I need to know if Docutils need source files
> > > to be in reStructuredText format before converting them to HTML,
> > > LaTeX, man-pages, open-document or XML.

> > Yes, currently reStructuredText ist the only input format for Docutils.

> Well actually myst-parser is a Markdown to docutils AST renderer
> https://myst-parser.readthedocs.io, it is generally used via sphinx,
> but the base renderer is purely docutils. It also underpins
> https://myst-nb.readthedocs.io<https://myst-nb.readthedocs.io/en/latest/>
> and http://jupyterbook.org, to render Jupyter notebooks to docutils AST

Thank you for the link. When trying to install the myst-parser via pip3,
I unfortunately got a lot of unwanted requirements (one more Docutils and
Sphinx installation + several helpers).

The following proof-of-concept of a Markdown to HTML front-end therefore
relies on recommonmark::

  #!/usr/bin/env python
  # -*- coding: utf8 -*-
  # :Copyright: © 2020 Günter Milde.
  # :License: Released under the terms of the `2-Clause BSD license`_
  #
  # .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
  """
  A minimal front end to the Docutils Publisher, parsing CommonMark markdown files
  with `recommonmark` and producing HTML 5 documents.
  
  The output is also valid XML.
  """
  from docutils.core import publish_cmdline, default_description
  
  from recommonmark.parser import CommonMarkParser
  
  mdparser = CommonMarkParser()
  
  description = (u'Generate HTML5 documents from standalone '
                 u'MarkDown (CommonMark) sources.\n'
                 + default_description)
  
  publish_cmdline(parser=mdparser, writer_name='html5',
                  description=description)

This allows to convert your standalonde README.md document into HTML, say.

Similar front-ends would be easy to construct replacing the
recommonmark.parser with the myst-parser or the writer name with the name of
other standard Docutils writers.

A better integration would include a "rmd" parser module that integrates the
configurion of the markdown parser into the standard Docutils configuration
framework.
https://docutils.sourceforge.io/docs/user/config.html




Thanks,
Günter

--

A: It reverses the normal flow of conversation.
Q: What's wrong with top-posting?
A: Top-posting.
Q: What's the biggest scourge on plain text email discussions?

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

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

On 2020-09-24, Chris Sewell wrote:

> Indeed, the Docutils maintainers may be able to offer a better
> explanation, but IMO there are a few distinct aspects of Docutils to
> bare in mind:

> - The Docutils Abstract Syntax Tree (AST, aka doctree): this is the
>   structure that holds the document in an input/output agnostic format.
>   It has (in principal) nothing to do with the input format
>   reStructuredText/Markdown/etc, or the output format HTML/LaTeX/etc

The specification https://www.python.org/dev/peps/pep-0258/#document-tree
describes the `Document Tree` as a data structure is similar to a DOM tree,
but with specific node names (classes) instead of DOM's generic nodes.
The schema is documented in an XML DTD (eXtensible Markup Language
Document Type Definition) docutils.dtd__

__ http://docutils.sourceforge.net/docs/ref/docutils.dtd

> - The input parser, which converts a (text) file to the AST, of which
>   is the reStructuredText parser is the primary example. MyST does the
>   same for Markdown, and also “shares" reStructuredText’s
>   role/directive syntax extension system

Actually, the `parser` parses an input string presented to it by the
`reader` (it may come from file or other sources).

> - The output renderer, which converts the AST to the output format

In Docutils, this component is called a `writer`.

> What sphinx does is, in essence, extend the Docutils render process to
> better deal with multiple, inter-connected, documents (e.g.  a full
> website/book). For example, adding cross-document referencing and AST
> caching.

Spinx also provides a framework for several extensions, including 
at least two Markdown parsers (recommonmark and myst-parser).

These parsers should in principle also work with core Docutils. However,
I don't know of any implementation or documentation for this combination.

It would be a nice advancement, to have frontends similar to rst2...
that work with markdown input.

Another idea would be to add a ``:format:`` option to the "include"
directive that allows things like::

  .. include:: README.md
     :format: markdown
     
This could be an optional feature depending on an external markdown
parser that can be imported from Docutils. (Somewhat similar to
syntax-highlight with Pygments or some HTML-Math-Output options.)


Yet another idea is a Docutils-XML parser that would parse the native
Docutils XML format - allowing to store parsed documents as XML and
offers a gateway to the XML world (e.g. converting any input to Docutils
XML via XSLT).


Günter

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Chris S. <chr...@ho...>]

Indeed, the Docutils maintainers may be able to offer a better explanation, but IMO there are a few distinct aspects of Docutils to bare in mind:

- The Docutils Abstract Syntax Tree (AST, aka doctree): this is the structure that holds the document in an input/output agnostic format.
   It has (in principal) nothing to do with the input format reStructuredText/Markdown/etc, or the output format HTML/LaTeX/etc
-  The input parser, which converts a (text) file to the AST, of which is the reStructuredText parser is the primary example.
    MyST does the same for Markdown, and also “shares" reStructuredText’s  role/directive syntax extension system
- The output renderer, which converts the AST to the output format

What sphinx does is, in essence, extend the Docutils render process to better deal with multiple, inter-connected, documents (e.g.  a full website/book). For example, adding cross-document referencing and AST caching.

> On 24 Sep 2020, at 01:29, Marc Rintsch <ma...@ri...> wrote:
> 
> On 23.09.20 23:31, Omer Shommo wrote:
>> […] So, is it safe to say that SPHINX uses DOCUTILS to convert plain text files into reStructuredText (.rst) files?
> 
> No, not at all.  Docutils converts reStructuredText into different output formats like HTML and LaTeX (which in turn can be converted to PDF).  Sphinx extends Docutils by some roles and directives and generates things like index pages.
> 
> Sphinx/Docutils doesn't convert *into* reStructuredText but *from* reStructuredText.
> 
> Ciao,
> 	Marc 'BlackJack' Rintsch
> -- 
> “A designer knows he has achieved perfection not when there is
> nothing left to add, but when there is nothing left to take away.”
>  -- Antoine de Saint-Exupéry
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Marc R. <ma...@ri...>]

On 23.09.20 23:31, Omer Shommo wrote:
> […] So, is it safe to say that SPHINX uses DOCUTILS to convert 
> plain text files into reStructuredText (.rst) files?

No, not at all.  Docutils converts reStructuredText into different 
output formats like HTML and LaTeX (which in turn can be converted to 
PDF).  Sphinx extends Docutils by some roles and directives and 
generates things like index pages.

Sphinx/Docutils doesn't convert *into* reStructuredText but *from* 
reStructuredText.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“A designer knows he has achieved perfection not when there is
  nothing left to add, but when there is nothing left to take away.”
   -- Antoine de Saint-Exupéry

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Omer S. <os...@gm...>]

Thanks Chris. So, is it safe to say that SPHINX uses DOCUTILS to convert
plain text files into reStructuredText (.rst) files?

Thanks

On Wed, Sep 23, 2020 at 7:06 AM <
doc...@li...> wrote:

> Send Docutils-users mailing list submissions to
>         doc...@li...
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.sourceforge.net/lists/listinfo/docutils-users
> or, via email, send a message with subject or body 'help' to
>         doc...@li...
>
> You can reach the person managing the list at
>         doc...@li...
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Docutils-users digest..."
> Today's Topics:
>
>    1. Is reStructuredText required for conversion to HTML (Omer Shommo)
>    2. Re: Is reStructuredText required for conversion to HTML
>       (Guenter Milde)
>    3. Re: Is reStructuredText required for conversion to HTML
>       (chris sewell)
>
>
>
> ---------- Forwarded message ----------
> From: Omer Shommo <os...@gm...>
> To: docutils-users <doc...@li...>
> Cc:
> Bcc:
> Date: Tue, 22 Sep 2020 22:02:05 -0500
> Subject: [Docutils-users] Is reStructuredText required for conversion to
> HTML
> Hello Everybody,
>
> I am new to docutils. I need to know if Docutils need source files to be
> in reStructuredText format before converting them to HTML, LaTeX,
> man-pages, open-document or XML
>
> Thanks
>
>
>
> ---------- Forwarded message ----------
> From: Guenter Milde <mi...@us...>
> To: doc...@li...
> Cc:
> Bcc:
> Date: Wed, 23 Sep 2020 06:36:18 -0000 (UTC)
> Subject: Re: [Docutils-users] Is reStructuredText required for conversion
> to HTML
> On 2020-09-23, Omer Shommo wrote:
>
> > Hello Everybody,
>
> > I am new to docutils. I need to know if Docutils need source files to be
> in
> > reStructuredText format before converting them to HTML, LaTeX, man-pages,
> > open-document or XML
>
> Yes, currently reStructuredText_ ist the only input format for Docutils.
>
> Günter
>
>
> .. _reStructuredText:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
>
>
>
>
>
> ---------- Forwarded message ----------
> From: chris sewell <chr...@ho...>
> To: Guenter Milde <mi...@us...>
> Cc: "doc...@li..." <
> doc...@li...>
> Bcc:
> Date: Wed, 23 Sep 2020 06:54:35 +0000
> Subject: Re: [Docutils-users] Is reStructuredText required for conversion
> to HTML
> Well actually myst-parser is a Markdown to docutils AST renderer
> https://myst-parser.readthedocs.io, it is generally used via sphinx, but
> the base renderer is purely docutils.
> It also underpins https://myst-nb.readthedocs.io
> <https://myst-nb.readthedocs.io/en/latest/> and http://jupyterbook.org,
> to render Jupyter notebooks to docutils AST
>
> Kind Regards,
> Chris
>
> On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users <
> doc...@li...> wrote:
>
> On 2020-09-23, Omer Shommo wrote:
>
> Hello Everybody,
>
>
> I am new to docutils. I need to know if Docutils need source files to be in
>
> reStructuredText format before converting them to HTML, LaTeX, man-pages,
>
> open-document or XML
>
>
> Yes, currently reStructuredText_ ist the only input format for Docutils.
>
> Günter
>
>
> .. _reStructuredText:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>

Re: [Docutils-users] Is reStructuredText required for conversion to HTML

[chris s. <chr...@ho...>]

Well actually myst-parser is a Markdown to docutils AST renderer https://myst-parser.readthedocs.io, it is generally used via sphinx, but the base renderer is purely docutils.
It also underpins https://myst-nb.readthedocs.io<https://myst-nb.readthedocs.io/en/latest/> and http://jupyterbook.org, to render Jupyter notebooks to docutils AST

Kind Regards,
Chris

On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users <doc...@li...> wrote:

On 2020-09-23, Omer Shommo wrote:

Hello Everybody,

I am new to docutils. I need to know if Docutils need source files to be in
reStructuredText format before converting them to HTML, LaTeX, man-pages,
open-document or XML

Yes, currently reStructuredText_ ist the only input format for Docutils.

Günter


.. _reStructuredText: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



_______________________________________________
Docutils-users mailing list
Doc...@li...
https://lists.sourceforge.net/lists/listinfo/docutils-users

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

Re: [Docutils-users] Is reStructuredText required for conversion to HTML

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

On 2020-09-23, Omer Shommo wrote:

> Hello Everybody,

> I am new to docutils. I need to know if Docutils need source files to be in
> reStructuredText format before converting them to HTML, LaTeX, man-pages,
> open-document or XML

Yes, currently reStructuredText_ ist the only input format for Docutils.

Günter


.. _reStructuredText: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

[Docutils-users] Is reStructuredText required for conversion to HTML

[Omer S. <os...@gm...>]

Hello Everybody,

I am new to docutils. I need to know if Docutils need source files to be in
reStructuredText format before converting them to HTML, LaTeX, man-pages,
open-document or XML

Thanks

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

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

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:

> Hello,

> I am downloading reStructuredText from our website. These files are
> used along with Sphinx to create the sites on-line (ReadTheDocs)
> documentation.

> I want to ‘tag’ words within the downloaded reST files ahead of
> converting these to XHTML which is used to build the index at the end
> of a generated PDF document. 
> The tagged rest documents are loaded back
> to the sites repository so that the tagging is persisted. 

Mind, that creating an index is not supported by Docutils but an addition by
Sphinx. So, for questions relating to index generation better ask the Sphinx
people.

> So I am looking for a way of adding tags that will be ignored by the
> sites processes.  

The question, how to add information to an rST source that does
not appear in the output is more generic, so I'll try an anwer.

> I need to tag specific words inline so ‘.. Comments’
> will not work, but perhaps there is another way?

More than one with different side effects and preconditions.

What works best depends on your use case, so a minimal example or more
detailed description is required for a more detailed anwser.

> My simple naïve approach was to embed html comments ahead of the
> word(s), for example putting <!—startTag --> before the words and
> <!—endTag --> after them.  This worked for my processes but the
> web-site documentation processes don’t keep these as comments and they
> appear on the screen.

Did you put the HTML comments in "raw" roles?
(In contrast to Markup, rST allows raw HTML only inside a "raw" directive or
role.)

However, I suggest defining a custom role that allows to add class values
to inline text.
Another option would be using substitutions.

I hope this gets you started.


Günter

[Docutils-users] How to add index information

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

Hello,

I am downloading reStructuredText from our website. These files are used along with Sphinx to create the sites on-line (ReadTheDocs) documentation.

I want to ‘tag’ words within the downloaded reST files ahead of converting these to XHTML which is used to build the index at the end of a generated PDF document. The tagged rest documents are loaded back to the sites repository so that the tagging is persisted. So I am looking for a way of adding tags that will be ignored by the sites processes.  I need to tag specific words inline so ‘.. Comments’ will not work, but perhaps there is another way?

My simple naïve approach was to embed html comments ahead of the word(s), for example putting <!—startTag --> before the words and <!—endTag --> after them.  This worked for my processes but the web-site documentation processes don’t keep these as comments and they appear on the screen.

Any suggestions would be appreciated.

Re: [Docutils-users] Output format argument for meta directive

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

On 2020-08-12, Rickard Armiento wrote:
> Hi,

> I've been working on a set of transformations of reST to various output, 
> most notably to reveal.js-based slides (I have a repo at 
> https://github.com/rartino/httk-rsttools - but it is still very much 
> work in progress.)

> In the 'Directives' documentation file, the meta directive is presently 
> the only implemented directive under the 'HTML-Specific' headline and 
> its description is indeed very HTML-specific.

> I have multiple times found myself looking for a way to include metadata 
> in my source documents for use in other contexts and for other output 
> formats, and thus found the HTML-only nature of meta inelegant.

> Is there a reason the 'meta' directive doesn't take an output format 
> argument, making it possible to use it for meta-data in contexts also 
> outside HTML? I.e., to make it work much like the argument to the 'raw' 
> directive, e.g.:
>    .. meta:: pdf

> Is this something that could be considered for inclusion in the reST 
> standard?

Making "meta" available for other formats is a valuable extension.

There is a already some support in the ODF/ODT writer, however, I don't know
whether it works and how to test.
There is also a TODO comment in the LaTeX writer.

I wonder whether an output format option would be required or if it could be
made generic (with formats not supporting meta giving an INFO or WARNING
message about ignoring the content).
(Different meta content for different outputs from the same source could also
be achieved with more generic settings and class argument values.)

More detailled suggestions and patches are welcome and will be discussed
here or in the developers list. 
Alternatively, an enhancement ticket could be opened at
https://sourceforge.net/p/docutils/feature-requests/
so the idea is not forgotten in the long term.


Thank you for the suggestion,
Günter

Re: [Docutils-users] Output format argument for meta directive

[engelbert g. <eng...@gm...>]

hei

i assume the meta directive is only in html, because it stems from html

to get a better understanding of what we are doing, use cases would be very
helpful

cheers

On Wed, 12 Aug 2020 at 10:09, Rickard Armiento <ric...@gm...>
wrote:

> Hi,
>
> I've been working on a set of transformations of reST to various output,
> most notably to reveal.js-based slides (I have a repo at
> https://github.com/rartino/httk-rsttools - but it is still very much
> work in progress.)
>
> In the 'Directives' documentation file, the meta directive is presently
> the only implemented directive under the 'HTML-Specific' headline and
> its description is indeed very HTML-specific.
>
> I have multiple times found myself looking for a way to include metadata
> in my source documents for use in other contexts and for other output
> formats, and thus found the HTML-only nature of meta inelegant.
>
> Is there a reason the 'meta' directive doesn't take an output format
> argument, making it possible to use it for meta-data in contexts also
> outside HTML? I.e., to make it work much like the argument to the 'raw'
> directive, e.g.:
>    .. meta:: pdf
>
> Is this something that could be considered for inclusion in the reST
> standard?
>
> Best,
> Rickard
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] Output format argument for meta directive

[Rickard A. <ric...@gm...>]

Hi,

I've been working on a set of transformations of reST to various output, 
most notably to reveal.js-based slides (I have a repo at 
https://github.com/rartino/httk-rsttools - but it is still very much 
work in progress.)

In the 'Directives' documentation file, the meta directive is presently 
the only implemented directive under the 'HTML-Specific' headline and 
its description is indeed very HTML-specific.

I have multiple times found myself looking for a way to include metadata 
in my source documents for use in other contexts and for other output 
formats, and thus found the HTML-only nature of meta inelegant.

Is there a reason the 'meta' directive doesn't take an output format 
argument, making it possible to use it for meta-data in contexts also 
outside HTML? I.e., to make it work much like the argument to the 'raw' 
directive, e.g.:
   .. meta:: pdf

Is this something that could be considered for inclusion in the reST 
standard?

Best,
Rickard