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

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

[Docutils-users] set class on title

[Alan G. I. <ai...@am...>]

1. Using rst2html5, trying to set a class on the title instead sets it on `main`.
Similarly, trying to set it on a header instead sets it on a section.
Is this intentional?

2. Separately, does including a `main` element have a point? Is there some way
to write an reST document that would have content outside of `main`?

Thanks,
Alan Isaac

[Docutils-users] Approachability & documentation, regarding Sphinx use-cases

[Joachim J. <jo...@ja...>]

Hello,

I wanted to let you know that a discussion started in the sphinx tracker, around the developer experience problems surrounding sphinx and docutils, when trying to develop new sphinx extensions.

If that’s something you have an interest in following, I encourage you to take part into the discussion at https://github.com/sphinx-doc/sphinx/issues/8039

Thank you,
Best
Joachim Jablon

[Docutils-users] Registering a transform that always runs, without attaching it to a custom component

[Clément Pit-C. <cpi...@gm...>]

Hi there,

I have a custom directive FooDirective.  It creates a custom pending node to run FooTransform.  FooTransform gathers all pending foo nodes and applies a transformation.
The results are cached in a file, because the transformation runs costly computations.

At the moment, users of the directive just call docutils.directives.register_directive('foo', FooDirective).  There's one problem: I don't have any 'foo's in the document, the cache should be cleared.  But, with no 'foo's, no pending node is added and the transform isn't executed; hence, the cache isn't cleared.

How can I register a directive that always runs? I'm aware of the get_transform method on components, but I don't have a custom component; I'm just writing a directive.

In Sphinx I'd use app.add_transform; is there a Docutils equivalent?
Or is there a better way to do this?

Thanks!

Re: [Docutils-users] Content block expected for the "raw" directive; none found.

[Saša J. <go...@at...>]

Marc Rintsch writes:

> There needs to be an empty line between the directive and its content block.

Ahh...I was convinced that I tried that option and that it failled too,
but you're correct. :-)

Thanks!


Sincerely,
Gour

-- 
A person who is not disturbed by the incessant flow of
desires — that enter like rivers into the ocean, which is
ever being filled but is always still — can alone achieve
peace, and not the man who strives to satisfy such desires.

Re: [Docutils-users] Content block expected for the "raw" directive; none found.

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

On 24.05.20 12:07, Saša Janiška wrote:
> while writing content for Nikola (static-site-generator) I've a need to
> display counter for downloaded links and first of all tried with 'raw'
> directive as in the 2nd definition, but I get: "Content block expected
> for the "raw" directive; none found."
> 
> Then I found some workaround to use it inline, like in the 1st
> definition and that works, but wonder what is wrong with the 2nd
> example?
> 
> - - - - - - - - - - -
> 
> .. role:: raw-html(raw)
>     :format: html
>              
> Lectures
> -----------
> 
> 1. lesson: `Lesson I <https://sub.tld/click.php?id=1>`_ (:raw-html:`<script>ccount_display('1');</script>`)
> 
>     
> 2. lesson `Lesson II <https://sub.tld/click.php?id=2>`_
> 
> .. raw:: html
>     <script>ccount_display('2');</script>
> 
> - - - - - - - - - - - -
> 
> Any hint?

There needs to be an empty line between the directive and its content block.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“»I'm not going to ride on a magic carpet!« he hissed.
  »I'm afraid of grounds!«
  »You mean heights,« said Conina. »And stop being silly.«
  »I know what I mean! It's the grounds that kill you!«”
                              -- Terry Pratchett, Sourcery

[Docutils-users] Content block expected for the "raw" directive; none found.

[Saša J. <go...@at...>]

Hello,

while writing content for Nikola (static-site-generator) I've a need to
display counter for downloaded links and first of all tried with 'raw'
directive as in the 2nd definition, but I get: "Content block expected
for the "raw" directive; none found."

Then I found some workaround to use it inline, like in the 1st
definition and that works, but wonder what is wrong with the 2nd
example?

- - - - - - - - - - -

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

1. lesson: `Lesson I <https://sub.tld/click.php?id=1>`_ (:raw-html:`<script>ccount_display('1');</script>`)

   
2. lesson `Lesson II <https://sub.tld/click.php?id=2>`_

.. raw:: html
   <script>ccount_display('2');</script>

- - - - - - - - - - - -

Any hint?


Sincerely,
Gour

-- 
For him who has conquered the mind, the mind is the best of
friends; but for one who has failed to do so, his mind will
remain the greatest enemy.

Re: [Docutils-users] Formatting a reStructredText document

[Matěj C. <mc...@ce...>]

On 2020-05-04, 10:57 GMT, Eric Chinaka wrote:
> How do you inset page numbers?

You don’t. docutils are platform independent and page numbers 
have any meaning only paged output (e.g., LaTeX), whereas they 
are completely meaningless elsewhere (HTML, ePub). Therefore, 
page numbers are matter of the particular output filters and 
they can be fiddled with in the particular section of your 
`docutils.conf`_.

Best,

Matěj

.. _`docutils.conf`:
    https://docutils.sourceforge.io/docs/user/config.html

[Docutils-users] Formatting a reStructredText document

[Eric C. <Eri...@ne...>]

I am trying to format a document in reStructredText.

How do you inset page numbers?

Regards.




Eric Chinaka

Scientist

Tel: 012 305 5428

Fax: +27 12 305 5166

Cell: +27 71 917 6270

Email: Eri...@ne...

Website: www.necsa.co.za<http://www.necsa.co.za>

[cid:image507b84.JPG@0c6da7e5.4b860146]<http://>

[Facebook]<https://web.facebook.com/necsasoc/>  [Twitter] <https://twitter.com/necsa_Ltd>       [LinkedIn] <https://www.linkedin.com/company/necsa/>



________________________________

This message contains confidential information and is intended only for the individual named. If you are not the named addressee you should not disseminate, distribute or copy this e-mail. Please notify the sender immediately by e-mail if you have received this e-mail by mistake and delete this e-mail from your system. E-mail transmission cannot be guaranteed to be secure or error-free as information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does not accept liability for any errors or omissions in the contents of this message, which arise as a result of e-mail transmission. If verification is required please request a hard-copy version from NECSA.



#####################################################################################
Scanned by MailMarshal - Trustwave's comprehensive email content security solution. 
Download a free evaluation of MailMarshal at www.trustwave.com
#####################################################################################

Re: [Docutils-users] Docutils XML namespace?

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

On 2020-03-31, engelbert gruber wrote:

> [-- Type: text/plain, Encoding:  --]

> dont know (yet hopefully)
> but what is wrong with  tools/rst2xml.py ?


> On Tue, 31 Mar 2020 at 17:04, Mikhail Edoshin <mi...@on...> wrote:

>> Hi Engelbert,

>> I know docutils has a DTD for its XML. Does it have an official XML
>> namespace?

AFAIK, there is no official Docutils namespace name.

>> Context: I'm working with a tool that parses reST files into XML for use
>> in XML workflow. With all-XML workflow it's convenient to use a
>> dedicated namespace for reST, especially if it's reST with custom
>> extensions that may provide their own namespace. (E.g. one of such
>> extensions is going to be a generic '.. object:: XML' that embeds
>> literal foreign XML into reST.) 

Embedding literal XML is possible with ``.. raw::``.
What would a new "object" directive add?

>> I handle the conversion to XML myself
>> and right now I use a private namespace for reST elements. As I'm about
>> to publish the tool I wonder if there's an official reST namespace I
>> should be using instead. The tool is in its infancy and I can always
>> change things later, so it's not urgent.

Günter

Re: [Docutils-users] Docutils XML namespace?

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

dont know (yet hopefully)
but what is wrong with  tools/rst2xml.py ?


On Tue, 31 Mar 2020 at 17:04, Mikhail Edoshin <mi...@on...> wrote:

> Hi Engelbert,
>
> I know docutils has a DTD for its XML. Does it have an official XML
> namespace?
>
> Context: I'm working with a tool that parses reST files into XML for use
> in XML workflow. With all-XML workflow it's convenient to use a
> dedicated namespace for reST, especially if it's reST with custom
> extensions that may provide their own namespace. (E.g. one of such
> extensions is going to be a generic '.. object:: XML' that embeds
> literal foreign XML into reST.) I handle the conversion to XML myself
> and right now I use a private namespace for reST elements. As I'm about
> to publish the tool I wonder if there's an official reST namespace I
> should be using instead. The tool is in its infancy and I can always
> change things later, so it's not urgent.
>
> Kind regards,
> Mikhail
>
>
> _______________________________________________
> 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] Docutils XML namespace?

[Mikhail E. <mi...@on...>]

Hi Engelbert,

I know docutils has a DTD for its XML. Does it have an official XML 
namespace?

Context: I'm working with a tool that parses reST files into XML for use 
in XML workflow. With all-XML workflow it's convenient to use a 
dedicated namespace for reST, especially if it's reST with custom 
extensions that may provide their own namespace. (E.g. one of such 
extensions is going to be a generic '.. object:: XML' that embeds 
literal foreign XML into reST.) I handle the conversion to XML myself 
and right now I use a private namespace for reST elements. As I'm about 
to publish the tool I wonder if there's an official reST namespace I 
should be using instead. The tool is in its infancy and I can always 
change things later, so it's not urgent.

Kind regards,
Mikhail

Re: [Docutils-users] HTML5 Translator footnote brackets missing

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

On 2020-02-24, Jan 'oglop' Gazda wrote:

> Hello,
> I've been playing around with a html5 translator for my pelican page and I
> noticed that html5 translator
> (docutils.writers.html5_polyglot.HTMLTranslator) is missing override
> of visit_footnote_reference which adds brackets around the numbers like
> this "Note [1]".
> This looks like a major change (maybe not intentional) but I could not find
> any reference in issues/bug or docs.

It is part of a major change, documented in
https://docutils.sourceforge.io/docs/user/html.html#html5-polyglot

  There is no hard-coded formatting information in the HTML document.
  Correct rendering of elements not directly supported by HTML depends on
  a CSS style sheet. 

> So I have a few questions:
> 1) What is the reason for dropping the brackets? (Bug or feature)

The "footnote-references" setting is translated to a class argument by
the "html5_polyglot" writer. The appearance of footnote reference markers
is defined using CSS. The default rules in "minimal.css" define::
  
      a.footnote-reference.brackets:before,
      dt.label > span.brackets:before { content: "["; }
      a.footnote-reference.brackets:after,
      dt.label > span.brackets:after { content: "]"; }


> 2) Would you recommend to use html5 translator or not yet?

This depends on your needs. The html5 writer is supported and ready to be
used but less "road tested". Also, it may still evolve so it may be
necessary to adapt custom style-sheets or define some configuration
setting for full backwards compatibility. For example, we may make use of
the more liberal rules of ID values in HTMTL5 to allow more sensible IDs
of sections with Greek or Russian headings or headings starting with
numbers (https://sourceforge.net/p/docutils/feature-requests/66/).

An overview of the various HTML export options is given in
https://docutils.sourceforge.io/docs/user/html.html
More details and background around the differences between the html4 and
html5 writers can be seen in the commented source
https://docutils.sourceforge.io/docutils/writers/html5_polyglot/__init__.py


> 3) Are there any plans or would devs consider a change or docs website
> style 

There are currently no plans for a major revamp. The documentation is
intentionally also a *showcase of Docutil's default output*.
This means that many aspects (fonts, font size, colours) are left at the
browser default settings and comfortable site navigation a la `Sphinx`__ is
not implemented.

OTOH, we are, of course, interested in a good user experience and open
for suggestions to improve.

> - it's really difficult to navigate
> and especially hard to read for people with dyslexia (me)?

Could you elaborate?

You may also consider generating local HTML documentation from the sources
shipped with the Docutils package. This allows using the HTML5 writer as
well as experimenting with the configuration settings or CSS styles.

Thanks,
Günter

__ https://www.sphinx-doc.org

Re: [Docutils-users] FileNotFoundError: [Errno 2] No such file or directory: '/usr/local/lib/python3.8/site-packages/html5css3/thirdparty/revealjs/css/theme/league.css'

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

Dear Patrick,

thank you for reporting a problem with rst2html5.

It seems that this is caused by an add-on not maintained as part of Docutils.

On 2020-02-23, Patrick Levell wrote:

> *COMMAND:* rst2html5 --jquery --reveal-js --pretty-print-code --traceback
> fortune.rst >deck1.html && o deck1.html

The settings "--jquery --reveal-js --pretty-print-code" are not supported by
the Docutils html5 writer.


> *Traceback* (most recent call last):
>   File "/usr/local/bin/rst2html5", line 11, in <module>
>     load_entry_point('rst2html5-tools==0.5.3', 'console_scripts',
> 'rst2html5')()
>   File "/usr/local/lib/python3.8/site-packages/html5css3/main.py", line 32,

The directory "html5css3" is not part of Docutils.
It seems to be from an alternative 3rd-party HTML5 writer.

Depending on your needs, you may try the Docutils html5 writer or report to
the author of the alternative implementation.


Günter