docutils-users

[Docutils-users] comments vs. directives

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

On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
...


>> >> The preamble seems to use no standard but a home-grown syntax that
>> >> looks confusingly similar to reStructuredtext directives.  

>> > How so?  

...

Steps to find out why I call the current Rivista metadata syntax 
"confusingly similar" to Docutils directives:

* create a file containing

    .. title: My simple example

    .. title:: My simple example

* convert with rst2xml to see how the two statements are interpreted by
  the docutils "rst" parser.
  
* Optionally repeat with

    .. author: My Lin

    .. author:: My Lin

* Optionally repeat with

    .. date: 2025-10-09

    .. date: 2025-10-09


Günter

Re: [Docutils-users] comments vs. directives

[Schimon J. <sc...@fe...>]

Guenter. Good day.

I think that I already did that, after you asked, but upon my documents.

I have created a test file which is based only on your text.

Upon executing command rst2xml, Docutils outputs a couple of errors,
one for author and one for date.

I assume that these are errors of the directives author:: and date::
with two colons.


$ rst2xml rst_preambles_and_directives_sample.rst >rst_preambles_and_directives_sample.xml
rst_preambles_and_directives_sample.rst:7: (ERROR/3) Unknown directive type "author".

.. author:: My Lin

rst_preambles_and_directives_sample.rst:11: (ERROR/3) Invalid context: the "date" directive can only be used within a substitution definition.


Schimon

On Thu, 9 Oct 2025 18:46:31 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> ...
> 
> 
> >> >> The preamble seems to use no standard but a home-grown syntax
> >> >> that looks confusingly similar to reStructuredtext directives.
> >> >>   
> 
> >> > How so?    
> 
> ...
> 
> Steps to find out why I call the current Rivista metadata syntax 
> "confusingly similar" to Docutils directives:
> 
> * create a file containing
> 
>     .. title: My simple example
> 
>     .. title:: My simple example
> 
> * convert with rst2xml to see how the two statements are interpreted
> by the docutils "rst" parser.
>   
> * Optionally repeat with
> 
>     .. author: My Lin
> 
>     .. author:: My Lin
> 
> * Optionally repeat with
> 
>     .. date: 2025-10-09
> 
>     .. date: 2025-10-09
> 

Did you mean to add two consequent colons to the second instance of
"date" (i.e. "date::")?

> 
> Günter
> 
> 
> 
> _______________________________________________
> 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] [SPAM] Re: Atom Syndication Format minimal example.

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

Dear Schimon,

thanks for the new example.

On 2025-10-10, Schimon Jehudah via Docutils-users wrote:
> On Thu, 9 Oct 2025 17:22:42 -0000 (UTC)
> Guenter Milde via Docutils-users <doc...@li...>
> wrote:

>> I just want a `minimal working example` as (opposed to illustrative
>> examples):

>>   The important feature of a minimal reproducible example is that it
>>   is as small and as simple as possible, such that it is just
>>   sufficient to demonstrate the problem, [...]
>>   -- https://en.wikipedia.org/wiki/Minimal_reproducible_example

...

> Are the attached files qualified as a proper example, or should I
> create a reduced version of the code that realizes that task?

Is getting close, but I would still call it an "illustrative example"
or "use case".  A "minimal example" could be even smaller.

For example, the content could be just two small paragraphs.
(However, it should keep containing at least one element that
distinguishes reStructuredText from plain text or other markup.)

Generally, a "minimal working example" would also include a description
of the steps to get the result.  
However, currently I will not try to reproduce the results, so this is
not required here. 

Günter


> [-- Type: text/x-rst, Encoding: 7bit, Filename: rst.rst --]

> .. authors: Schimon Jehudah Zachary , xmpp:sc...@pi...?message
> .. date: 2025-07-14 00:00:00 UTC
> .. description: A markup syntax.
> .. link: rst
> .. related:
>    reStructuredText homesite , https://docutils.sourceforge.io/rst.html
>    reStructuredText tutorials , https://docutils.sourceforge.io/docs/ref/rst/
> .. slug: rst
> .. tags:
>    Documentation, Publishing, Python Computer language, reStructuredText, rST
> .. title: reStructuredText
> .. type: text

> reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext
> markup syntax and parser system. It is useful for in-line program documentation
> (such as Python docstrings), for quickly creating simple internet pages, and for
> standalone documents.

...

> .. epigraph::
>    "reStructuredText" is ONE word, not two!