You can subscribe to this list here.
2002 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
(3) |
Sep
(15) |
Oct
(21) |
Nov
(18) |
Dec
(59) |
---|---|---|---|---|---|---|---|---|---|---|---|---|
2003 |
Jan
(43) |
Feb
(35) |
Mar
(78) |
Apr
(65) |
May
(163) |
Jun
(169) |
Jul
(137) |
Aug
(77) |
Sep
(47) |
Oct
(27) |
Nov
(43) |
Dec
(68) |
2004 |
Jan
(61) |
Feb
(39) |
Mar
(11) |
Apr
(42) |
May
(86) |
Jun
(82) |
Jul
(24) |
Aug
(26) |
Sep
(37) |
Oct
(62) |
Nov
(131) |
Dec
(43) |
2005 |
Jan
(31) |
Feb
(56) |
Mar
(65) |
Apr
(165) |
May
(106) |
Jun
(97) |
Jul
(65) |
Aug
(150) |
Sep
(78) |
Oct
(115) |
Nov
(41) |
Dec
(26) |
2006 |
Jan
(50) |
Feb
(39) |
Mar
(56) |
Apr
(67) |
May
(89) |
Jun
(68) |
Jul
(116) |
Aug
(65) |
Sep
(58) |
Oct
(103) |
Nov
(28) |
Dec
(52) |
2007 |
Jan
(92) |
Feb
(60) |
Mar
(124) |
Apr
(96) |
May
(69) |
Jun
(79) |
Jul
(25) |
Aug
(22) |
Sep
(7) |
Oct
(17) |
Nov
(27) |
Dec
(32) |
2008 |
Jan
(57) |
Feb
(87) |
Mar
(51) |
Apr
(43) |
May
(56) |
Jun
(62) |
Jul
(25) |
Aug
(82) |
Sep
(58) |
Oct
(42) |
Nov
(38) |
Dec
(86) |
2009 |
Jan
(50) |
Feb
(33) |
Mar
(84) |
Apr
(90) |
May
(109) |
Jun
(37) |
Jul
(22) |
Aug
(51) |
Sep
(93) |
Oct
(86) |
Nov
(31) |
Dec
(62) |
2010 |
Jan
(33) |
Feb
(57) |
Mar
(62) |
Apr
(43) |
May
(30) |
Jun
(49) |
Jul
(20) |
Aug
(40) |
Sep
(152) |
Oct
(38) |
Nov
(15) |
Dec
(32) |
2011 |
Jan
(29) |
Feb
(25) |
Mar
(65) |
Apr
(45) |
May
(27) |
Jun
(11) |
Jul
(14) |
Aug
(8) |
Sep
(13) |
Oct
(117) |
Nov
(60) |
Dec
(19) |
2012 |
Jan
(23) |
Feb
(32) |
Mar
(24) |
Apr
(41) |
May
(56) |
Jun
(24) |
Jul
(15) |
Aug
(11) |
Sep
(26) |
Oct
(21) |
Nov
(12) |
Dec
(31) |
2013 |
Jan
(32) |
Feb
(24) |
Mar
(39) |
Apr
(44) |
May
(44) |
Jun
(8) |
Jul
(9) |
Aug
(12) |
Sep
(34) |
Oct
(19) |
Nov
(5) |
Dec
(9) |
2014 |
Jan
(22) |
Feb
(12) |
Mar
(7) |
Apr
(2) |
May
(13) |
Jun
(17) |
Jul
(8) |
Aug
(10) |
Sep
(7) |
Oct
(4) |
Nov
|
Dec
(39) |
2015 |
Jan
(13) |
Feb
(12) |
Mar
(12) |
Apr
(40) |
May
(5) |
Jun
(22) |
Jul
(3) |
Aug
(42) |
Sep
(5) |
Oct
(10) |
Nov
|
Dec
(10) |
2016 |
Jan
(9) |
Feb
(43) |
Mar
(5) |
Apr
(14) |
May
(17) |
Jun
(5) |
Jul
(5) |
Aug
(22) |
Sep
(5) |
Oct
|
Nov
(4) |
Dec
(18) |
2017 |
Jan
(28) |
Feb
(29) |
Mar
(9) |
Apr
(23) |
May
(48) |
Jun
(5) |
Jul
(32) |
Aug
(9) |
Sep
(13) |
Oct
(13) |
Nov
(6) |
Dec
(4) |
2018 |
Jan
(6) |
Feb
(5) |
Mar
(1) |
Apr
(2) |
May
(5) |
Jun
(17) |
Jul
(12) |
Aug
(15) |
Sep
|
Oct
(2) |
Nov
|
Dec
|
2019 |
Jan
|
Feb
(6) |
Mar
(3) |
Apr
(5) |
May
(10) |
Jun
(6) |
Jul
(6) |
Aug
|
Sep
(11) |
Oct
(18) |
Nov
(10) |
Dec
(7) |
2020 |
Jan
(3) |
Feb
(14) |
Mar
(2) |
Apr
(1) |
May
(5) |
Jun
|
Jul
(1) |
Aug
(11) |
Sep
(8) |
Oct
|
Nov
(1) |
Dec
(14) |
2021 |
Jan
(7) |
Feb
(2) |
Mar
(1) |
Apr
(8) |
May
(23) |
Jun
(7) |
Jul
(10) |
Aug
(1) |
Sep
|
Oct
(7) |
Nov
(10) |
Dec
(2) |
2022 |
Jan
|
Feb
(21) |
Mar
|
Apr
(3) |
May
(7) |
Jun
(4) |
Jul
(1) |
Aug
|
Sep
(3) |
Oct
|
Nov
|
Dec
|
2023 |
Jan
(18) |
Feb
|
Mar
(1) |
Apr
|
May
(9) |
Jun
|
Jul
|
Aug
(5) |
Sep
|
Oct
|
Nov
|
Dec
|
2024 |
Jan
|
Feb
(2) |
Mar
(3) |
Apr
(5) |
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
(2) |
Nov
|
Dec
(2) |
2025 |
Jan
(4) |
Feb
|
Mar
(2) |
Apr
(1) |
May
(3) |
Jun
(6) |
Jul
(22) |
Aug
(5) |
Sep
(9) |
Oct
(30) |
Nov
|
Dec
|
From: Schimon J. <sc...@fe...> - 2025-10-10 11:59:05
|
Günter. Good afternoon. I have just had a new realization, consequent to your mention of CSV. On Fri, 10 Oct 2025 10:20:51 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-10, Schimon Jehudah via Docutils-users wrote: > > >> > > >> >> The preamble [...] looks confusingly similar to > >> > > >> >> reStructuredtext directives. > > > Then, do you imply, by that statement, that it be a preferable > > practice for preambles to differ from reStructuredtext directives? > > I would have chosen a different syntax. > > However, considering the actual situation, I suggest keeping the > current syntax (maybe even reverting to use a semicolon). > I have changed preambles in accordance with The Atom Syndication Format, which the publishing project software "Rivista Voyager" focuses at. Applying CSV tables to preambles with multiple values would further allow, due to the built-in "csv" module of Python, to have a single function to handle different preambles, which would further allow to care for new attributes if needed. .. author: name,uri Schimon Jehudah Zachary , xmpp:sc...@pi...?message .. links: title,href,rel Metalinker.org - Why Metalink? , https://metalinker.org/why.html , related Metalinker: Integrating HTTP, FTP and P2P , https://torrentfreak.com/metalinker-integrating-http-ftp-and-p2p/ , related Metalink @ Packages Resources , http://metalink.packages.ro , related Shareaza Wiki , https://shareaza.sourceforge.net/mediawiki/Main_Page , related Gnutella2 Developer Network , https://g2.doxu.org , related Instead of spliting and counting and guessing of types of values of those preambles, those could be handled by this shorter code. import csv lines = csv_string.strip().split('\n') for i in csv.DictReader(lines): i Though, I would later solve how to retain values that include commas. "Quotation marks" do not solve this. Nevertheless, incorporating CSV is significantly better. > Günter > Schimon |
From: Guenter M. <mi...@us...> - 2025-10-10 10:21:08
|
On 2025-10-10, Schimon Jehudah via Docutils-users wrote: >> > > >> >> The preamble [...] looks confusingly similar to >> > > >> >> reStructuredtext directives. > Then, do you imply, by that statement, that it be a preferable practice > for preambles to differ from reStructuredtext directives? I would have chosen a different syntax. However, considering the actual situation, I suggest keeping the current syntax (maybe even reverting to use a semicolon). Günter |
From: Guenter M. <mi...@us...> - 2025-10-10 10:05:27
|
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! |
From: Schimon J. <sc...@fe...> - 2025-10-10 09:21:20
|
Günter. Good afternoon. On Fri, 10 Oct 2025 10:53:29 +0200 Guenter Milde <gm...@e-...> wrote: > Dear Schimon, > > Am 10.10.25 schrieb Schimon Jehudah: > > ... > > 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. > > Correct. > > With two colons, it is rST directive syntax. > With one colon, it is rST comment syntax. > > Add/remove one colon and you get unexpected results. > Now, I realize this. > This is what I meant with my statement that > > > > >> >> The preamble [...] looks confusingly similar to > > > >> >> reStructuredtext directives. > Then, do you imply, by that statement, that it be a preferable practice for preambles to differ from reStructuredtext directives? > ... > > > > * 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::")? > > Yes. I was confused. > Thank you. > Günter Schimon |
From: Schimon J. <sc...@fe...> - 2025-10-10 05:45:11
|
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. |
From: Schimon J. <sc...@fe...> - 2025-10-10 05:00:47
|
Guenter. Good day. Are the attached files qualified as a proper example, or should I create a reduced version of the code that realizes that task? Kindly, Schimon On Thu, 9 Oct 2025 17:22:42 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > > On Thu, 9 Oct 2025 Guenter Milde via Docutils-users wrote: > >> ... > > >> Please provide a **minimal** example. > >> (e.g. input to generate something like > >> https://en.wikipedia.org/wiki/Atom_(web_standard)#Example_of_an_Atom_1.0_feed) > >> > > > Pardon. I do not realize what is this for, unless you mean that by > > "standard" I should comply with the fields (XML elements) of The > > Atom Syndication Format. > > 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 > > Günter > |
From: Guenter M. <mi...@us...> - 2025-10-09 18:46:49
|
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 |
From: Schimon J. <sc...@fe...> - 2025-10-09 17:34:23
|
Guenter. Good evening. On Thu, 9 Oct 2025 16:30:13 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > Dear Schimon, > > On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > > > I want to conclude these realizations. > > > * Docutils has standard Preambles (Metadata) of its own. > > Docutils has no formal standards (RFCs or similar). > > However, the Docutils project maintains 2 formal specifications as > part of the public API. > > a) The `reStructuredText Markup Specification`__ > > __ > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html > b) The Docutils document model: > `The Docutils Document Tree`__ > `Docutils Generic XML document type definition`__ > > __ https://docutils.sourceforge.io/docs/ref/doctree.html > __ https://docutils.sourceforge.io/docs/ref/docutils.dtd > > The `reStructuredText Markup Specification` includes the definition of > `bibliographic fields`__. "This bibliographic data corresponds to the > front matter of a book, such as the title page and copyright page." > Whether the bibliographic fields can cleanly map to Atom Syndication > metadata is an open question. > > __ > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields > > There is also the `meta`__ standard directive and <meta> `Doctree > element`__ which provides an alternative to a comment for meta-data > that should be extracted from the XML version. > For example, the rST :: > > .. meta:: > :keywords: plaintext, markup language > :description lang=en: An amusing story > :description lang=fr: Une histoire amusante > > is parsed into the XML elements:: > > <meta content="plaintext, markup language" name="keywords"></meta> > <meta content="An amusing story" lang="en" > name="description"></meta> <meta content="Une histoire amusante" > lang="fr" name="description"></meta> > > __ > https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata > __ https://docutils.sourceforge.io/docs/ref/doctree.html#meta > > I will consider these metadata entries in addition to thise of The Atom Syndication Format, as project Rivista Voyager has a specific niche for the Atom format due to the idea of an XML-based internet implemented with Atom and XLink. gemini://woodpeckersnest.space/~schapps/journal/2025-10-08-a-hope-for-further-internet-federation-via-http.gmi gemini://woodpeckersnest.space/~schapps/journal/2025-08-10-an-analyses-of-the-benefits-of-ace.gmi gemini://woodpeckersnest.space/~schapps/journal/2025-07-29-announcing-ace.gmi > > > * It be preferable to comply with the standard structure of > > Docutils. > > I concluded from your answers so far, that you want to use > reStructuredText (rST) as input file format (as opposed to > rST content embedded in a file with different format). > Yes. Indeed. > In this scenario, I suggest utilising rST syntax constructs to > structure the meta-data. Then, the Docutils rST parser can provide > the meta-data in a structured form. > > Currently, meta-data is included as a series of rST comments and > parsed according to a simple ad-hoc format that is intuitive and > "natural" --- for its creator. > I will explore this. > > > * With XSLT, it is possible to transform Docutils XML into Atom, > > CSV, HTML, JSON, TSV, Twtxt, XHTML, etc. > > This is my understanding of the power of XSLT: > > * Docutils can generate output in its well defined, valid XML format. > * With the correct set of rules, XSLT can convert any valid XML to > other XML formats and more. > > Whether there are some limitations and whether writing the XSLT > rules/styles/templates required for this task is simpler than coding a > Docutils "writer" class in Python exceeds my knowledge. > (I am familiar with Python but not with XSLT.) > There are no limitations. There is only a consideration which is to include in produced XML files the necessary data for XSLT to process. Post script ----------- XSLT is XML or XHTML with XPath rules which have more possibilities and functionalities that CSS Selectors. I am a lawyer and I studied XSLT within less than 14 days while creating a stylesheet for Atom, RDF, and RSS. The first attempt was not spectacular, but it worked and it did the desired task well. https://git.xmpp-it.net/sch/StreamBurner XSLT is similar to so called "templating engines" such as Bottle.py, Django, Jinja2, PHP, Embedded Ruby (ERB), et cetera, yet unlike "templating engines" XSLT is standard and can be realized with any computer language which has modules for parsing of XML. > > Regards, > Günter > Thank you very much! Best, Schimon. |
From: Guenter M. <mi...@us...> - 2025-10-09 17:23:02
|
On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > On Thu, 9 Oct 2025 Guenter Milde via Docutils-users wrote: >> ... >> Please provide a **minimal** example. >> (e.g. input to generate something like >> https://en.wikipedia.org/wiki/Atom_(web_standard)#Example_of_an_Atom_1.0_feed) > Pardon. I do not realize what is this for, unless you mean that by > "standard" I should comply with the fields (XML elements) of The Atom > Syndication Format. 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 Günter |
From: Guenter M. <mi...@us...> - 2025-10-09 16:30:33
|
Dear Schimon, On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > I want to conclude these realizations. > * Docutils has standard Preambles (Metadata) of its own. Docutils has no formal standards (RFCs or similar). However, the Docutils project maintains 2 formal specifications as part of the public API. a) The `reStructuredText Markup Specification`__ __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html b) The Docutils document model: `The Docutils Document Tree`__ `Docutils Generic XML document type definition`__ __ https://docutils.sourceforge.io/docs/ref/doctree.html __ https://docutils.sourceforge.io/docs/ref/docutils.dtd The `reStructuredText Markup Specification` includes the definition of `bibliographic fields`__. "This bibliographic data corresponds to the front matter of a book, such as the title page and copyright page." Whether the bibliographic fields can cleanly map to Atom Syndication metadata is an open question. __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields There is also the `meta`__ standard directive and <meta> `Doctree element`__ which provides an alternative to a comment for meta-data that should be extracted from the XML version. For example, the rST :: .. meta:: :keywords: plaintext, markup language :description lang=en: An amusing story :description lang=fr: Une histoire amusante is parsed into the XML elements:: <meta content="plaintext, markup language" name="keywords"></meta> <meta content="An amusing story" lang="en" name="description"></meta> <meta content="Une histoire amusante" lang="fr" name="description"></meta> __ https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata __ https://docutils.sourceforge.io/docs/ref/doctree.html#meta > * It be preferable to comply with the standard structure of Docutils. I concluded from your answers so far, that you want to use reStructuredText (rST) as input file format (as opposed to rST content embedded in a file with different format). In this scenario, I suggest utilising rST syntax constructs to structure the meta-data. Then, the Docutils rST parser can provide the meta-data in a structured form. Currently, meta-data is included as a series of rST comments and parsed according to a simple ad-hoc format that is intuitive and "natural" --- for its creator. > * With XSLT, it is possible to transform Docutils XML into Atom, CSV, > HTML, JSON, TSV, Twtxt, XHTML, etc. This is my understanding of the power of XSLT: * Docutils can generate output in its well defined, valid XML format. * With the correct set of rules, XSLT can convert any valid XML to other XML formats and more. Whether there are some limitations and whether writing the XSLT rules/styles/templates required for this task is simpler than coding a Docutils "writer" class in Python exceeds my knowledge. (I am familiar with Python but not with XSLT.) Regards, Günter |
From: Schimon J. <sc...@fe...> - 2025-10-09 14:59:27
|
Sorry, I forgot to add XSLT. rST > (Docutils) > Docutils-XML > (XSLT) > Atom Syndication Format rST > (Docutils) > Docutils-XML > (XSLT) > JSON Feed rST > (Docutils) > Docutils-XML > (XSLT) > Twtxt rST > (Docutils) > Docutils-XML > (XSLT) > (X)HTML Schimon On Thu, 9 Oct 2025 17:56:33 +0300 Schimon Jehudah <sch@fedora.email> wrote: > Guenter. Good evening. > > Please see a newly proposed diagram. > > On Thu, 9 Oct 2025 17:19:26 +0300 > Schimon Jehudah via Docutils-users > <doc...@li...> wrote: > > > On Thu, 9 Oct 2025 12:48:47 -0000 (UTC) > > Guenter Milde via Docutils-users > > <doc...@li...> wrote: > > > > > On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > > > > > > >> What I am missing, is a user documentation. > > > > > > > There is no documentation yet. This software is subjected to > > > > further development. > > > > > > It helps to write/update user documentation in parallel (at least > > > a stub): > > > > > > If the implementation is hard to explain, it's a bad idea. > > > If the implementation is easy to explain, it may be a good > > > idea. > > > -- python -m this > > > > > > > Thank you for this comment. I will do so. > > > > > >> Also, I cannot find a description of the input format. > > > > > > >> The preamble seems to use no standard but a home-grown syntax > > > >> that looks confusingly similar to reStructuredtext directives. > > > >> > > > > > > > How so? > > > > > > :: > > > > > > .. title: My simple example > > > > > > .. title:: My simple example > > > > > > Convert with rst2xml and rst2html to see the difference. > > > > > > > In HTML, "Title ::" is realized into element "title" under element > > "head". > > > > In XML, "Title ::" is realized into attribute "title" of element > > "document". > > > > I think that the placement of these propertoes as attributes would > > definitely facilitate the XSL Transformation of XML Docutils into > > Atom Syndication Format with a designated XSLT stylesheet. > > > > Yet, I stil do not realize the reason for your comment. > > > > Is ityour comment, an explanatory comment or a comment that my rST > > documents have issues? > > > > > > > > > Do you mean that the use of multiple lines in which each > > > > semicolon segregates "title" and "address" is not to be > > > > considered as standard? > > > > > > It could be considered as CSV-variant. You would have to > > > > > > * document/motivate the use of this CSV variant > > > in the preamble fields of an rST document and > > > * write your own parser (or XSLT extraction rules) > > > to parse the raw field content.¹ > > > > > > > If I would produce CSV, then I would use my own parser, as I think > > that XSLT only works with JSON and XML, and probably other formats > > that can be queried. > > > > Nevertheless, I think that I realize your answer. > > > > > Also, the semicolon clashes with rST syntax in "authors" fields: > > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors > > > > > > > Thank you for this additional information. > > > > I will act upon this in a few hours. > > > > > ¹ rST supports CSV with the "CSV-table" directive > > > (and the separator defaulting to ","). > > > https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table > > > > > > Howver, you won't like to write:: > > > > > > :authors: .. csv-table:: > > > > > > > I apologise for asking this again, I think, yet I want to be > > certain. > > > > Is this fine to write this? (comma) > > > > .. author: > > BabylonObserver.com , https://babylonobserver.com > > The Babylon Observer , mailto:in...@ba... > > > > Or would it be appropriate to write this? (greater > and lesser < > > than) > > > > .. author: > > BabylonObserver.com <https://babylonobserver.com> > > The Babylon Observer <mailto:in...@ba...> > > > > > > > > > > > > > >> > I think that it would be nice for Docutils to have features > > > >> > for XML. > > > > > > >> If you want XML, you may try the docutils-XML writer -- > > > >> Docutils XML is a well defined XML format. > > > > > > >> It should be possible to generate HTML from Docutils XML with > > > >> XSLT styles. This could be a way to achieve a HTML variant that > > > >> is impossible via the Docutils HTML writers (but is lots of > > > >> work). > > > > > > > > > > This is interesting. > > > > > > > Then, it is possible to utilize an XSLT stylesheet to transform > > > > that XML to Atom Syndication Format, and an additional XSLT > > > > stylesheet to transform that XML to HTML; > > > > > > > Docutils XML > (XSLT) > Atom > > > > > > > Docutils XML > (XSLT) > HTML > > > > > > > Of course, it is also possible to utilize the current stylesheet > > > > which already transforms Atom to HTML. > > > > > > > Docutils XML > (XSLT) > Atom > (XSLT) > HTML > > > > > > > > > I'd try to re-use as much as possible. > > > > So, you advise to use the standard of Docutils instead of > > information that may be related to Atom or otherwise, are yes? > > > > > Atom is XML with the content embedded as HTML, > > > so maybe: > > > > > > * rST > (Rivista) > rST-preamble + rST-content > > > > > > * rST-preamble > (Docutils) > Docutils-XML > > > rST-content > (Docutils) > HTML > > > > > > > Reading the XML output, and seeing elements "paragraph", "block_quote" > for paragraphs, and "reference" for IRI/URI/URL (equivalent to HTML > element "a"), I thik that it should be possible to create an XSLT > styleshet which would transform the who Docutils XML documents into an > Atom Syndication Format document. > > rST > (Docutils) > Docutils-XML > Atom Syndication Format > rST > (Docutils) > Docutils-XML > JSON Feed > rST > (Docutils) > Docutils-XML > Twtxt > rST > (Docutils) > Docutils-XML > (X)HTML > > > This is what I currently do, and intend to further finalize. > > > > rST-preamble > (Docutils) > Atom-dict (title, summary, link, etc.) > > > > rST-content > (Docutils) > HTML > Atom-dict (content) > > > > Atom-dict > Atom-XML > > > > > * XML-preamble + HTML-content (XSLT) > Atom-XML > > > > > > > I think that I would have to merge the XML-preamble and > > HTML-content, in order to be able to produce an Atom-XML. > > > > > * Atom > (XSLT) > HTML > > > > > > > This procedure is already done. > > > > # Generate HTML of Atom > > filepath_xslt_atom = os.path.join( > > publish_properties.directory_xslt, filename_xslt) > > atom_as_element_tree = ParserXml.create_element_tree_from_file( > > filepath_atom) > > atom_html_as_str = ParserXslt.transform_data( > > atom_as_element_tree, filepath_xslt_atom) > > filepath_atom_html = os.path.join( > > directory_html, directory, identifier, "index.html") > > with open(filepath_atom_html, "w") as fn: fn.write(atom_html_as_str) > > > > > > > > Günter > > > > > > > Schimon > > > > > > Schimon |
From: Schimon J. <sc...@fe...> - 2025-10-09 14:56:57
|
Guenter. Good evening. Please see a newly proposed diagram. On Thu, 9 Oct 2025 17:19:26 +0300 Schimon Jehudah via Docutils-users <doc...@li...> wrote: > On Thu, 9 Oct 2025 12:48:47 -0000 (UTC) > Guenter Milde via Docutils-users > <doc...@li...> wrote: > > > On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > > > > >> What I am missing, is a user documentation. > > > > > There is no documentation yet. This software is subjected to > > > further development. > > > > It helps to write/update user documentation in parallel (at least a > > stub): > > > > If the implementation is hard to explain, it's a bad idea. > > If the implementation is easy to explain, it may be a good idea. > > > > -- python -m this > > > > Thank you for this comment. I will do so. > > > >> Also, I cannot find a description of the input format. > > > > >> The preamble seems to use no standard but a home-grown syntax > > >> that looks confusingly similar to reStructuredtext directives. > > >> > > > > > How so? > > > > :: > > > > .. title: My simple example > > > > .. title:: My simple example > > > > Convert with rst2xml and rst2html to see the difference. > > > > In HTML, "Title ::" is realized into element "title" under element > "head". > > In XML, "Title ::" is realized into attribute "title" of element > "document". > > I think that the placement of these propertoes as attributes would > definitely facilitate the XSL Transformation of XML Docutils into Atom > Syndication Format with a designated XSLT stylesheet. > > Yet, I stil do not realize the reason for your comment. > > Is ityour comment, an explanatory comment or a comment that my rST > documents have issues? > > > > > > Do you mean that the use of multiple lines in which each semicolon > > > segregates "title" and "address" is not to be considered as > > > standard? > > > > It could be considered as CSV-variant. You would have to > > > > * document/motivate the use of this CSV variant > > in the preamble fields of an rST document and > > * write your own parser (or XSLT extraction rules) > > to parse the raw field content.¹ > > > > If I would produce CSV, then I would use my own parser, as I think > that XSLT only works with JSON and XML, and probably other formats > that can be queried. > > Nevertheless, I think that I realize your answer. > > > Also, the semicolon clashes with rST syntax in "authors" fields: > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors > > > > Thank you for this additional information. > > I will act upon this in a few hours. > > > ¹ rST supports CSV with the "CSV-table" directive > > (and the separator defaulting to ","). > > https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table > > > > Howver, you won't like to write:: > > > > :authors: .. csv-table:: > > > > I apologise for asking this again, I think, yet I want to be certain. > > Is this fine to write this? (comma) > > .. author: > BabylonObserver.com , https://babylonobserver.com > The Babylon Observer , mailto:in...@ba... > > Or would it be appropriate to write this? (greater > and lesser < > than) > > .. author: > BabylonObserver.com <https://babylonobserver.com> > The Babylon Observer <mailto:in...@ba...> > > > > > > > > >> > I think that it would be nice for Docutils to have features for > > >> > XML. > > > > >> If you want XML, you may try the docutils-XML writer -- Docutils > > >> XML is a well defined XML format. > > > > >> It should be possible to generate HTML from Docutils XML with > > >> XSLT styles. This could be a way to achieve a HTML variant that > > >> is impossible via the Docutils HTML writers (but is lots of > > >> work). > > > > > > > This is interesting. > > > > > Then, it is possible to utilize an XSLT stylesheet to transform > > > that XML to Atom Syndication Format, and an additional XSLT > > > stylesheet to transform that XML to HTML; > > > > > Docutils XML > (XSLT) > Atom > > > > > Docutils XML > (XSLT) > HTML > > > > > Of course, it is also possible to utilize the current stylesheet > > > which already transforms Atom to HTML. > > > > > Docutils XML > (XSLT) > Atom > (XSLT) > HTML > > > > > > I'd try to re-use as much as possible. > > So, you advise to use the standard of Docutils instead of information > that may be related to Atom or otherwise, are yes? > > > Atom is XML with the content embedded as HTML, > > so maybe: > > > > * rST > (Rivista) > rST-preamble + rST-content > > > > * rST-preamble > (Docutils) > Docutils-XML > > rST-content > (Docutils) > HTML > > > Reading the XML output, and seeing elements "paragraph", "block_quote" for paragraphs, and "reference" for IRI/URI/URL (equivalent to HTML element "a"), I thik that it should be possible to create an XSLT styleshet which would transform the who Docutils XML documents into an Atom Syndication Format document. rST > (Docutils) > Docutils-XML > Atom Syndication Format rST > (Docutils) > Docutils-XML > JSON Feed rST > (Docutils) > Docutils-XML > Twtxt rST > (Docutils) > Docutils-XML > (X)HTML > This is what I currently do, and intend to further finalize. > > rST-preamble > (Docutils) > Atom-dict (title, summary, link, etc.) > > rST-content > (Docutils) > HTML > Atom-dict (content) > > Atom-dict > Atom-XML > > > * XML-preamble + HTML-content (XSLT) > Atom-XML > > > > I think that I would have to merge the XML-preamble and HTML-content, > in order to be able to produce an Atom-XML. > > > * Atom > (XSLT) > HTML > > > > This procedure is already done. > > # Generate HTML of Atom > filepath_xslt_atom = os.path.join( > publish_properties.directory_xslt, filename_xslt) > atom_as_element_tree = ParserXml.create_element_tree_from_file( > filepath_atom) > atom_html_as_str = ParserXslt.transform_data( > atom_as_element_tree, filepath_xslt_atom) > filepath_atom_html = os.path.join( > directory_html, directory, identifier, "index.html") > with open(filepath_atom_html, "w") as fn: fn.write(atom_html_as_str) > > > > > Günter > > > > Schimon > > Schimon |
From: Schimon J. <sc...@fe...> - 2025-10-09 14:45:31
|
Guenter. Good evening. I am stil contemplating after reading the recent couple of email messages, and I do not want to further bother you, especially when it is not necessary. I am writing this message just so that we have a clear context of the concern which we discuss of, and just for that purpose. I want to conclude these realizations. * Docutils has standard Preambles (Metadata) of its own. * It be preferable to comply with the standard structure of Docutils. * With XSLT, it is possible to transform Docutils XML into Atom, CSV, HTML, JSON, TSV, Twtxt, XHTML, etc. Are these correct conclusions? Kindly, Schimon |
From: Schimon J. <sc...@fe...> - 2025-10-09 14:19:48
|
On Thu, 9 Oct 2025 12:48:47 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > > >> What I am missing, is a user documentation. > > > There is no documentation yet. This software is subjected to further > > development. > > It helps to write/update user documentation in parallel (at least a > stub): > > If the implementation is hard to explain, it's a bad idea. > If the implementation is easy to explain, it may be a good idea. > > -- python -m this > Thank you for this comment. I will do so. > >> Also, I cannot find a description of the input format. > > >> The preamble seems to use no standard but a home-grown syntax that > >> looks confusingly similar to reStructuredtext directives. > > > How so? > > :: > > .. title: My simple example > > .. title:: My simple example > > Convert with rst2xml and rst2html to see the difference. > In HTML, "Title ::" is realized into element "title" under element "head". In XML, "Title ::" is realized into attribute "title" of element "document". I think that the placement of these propertoes as attributes would definitely facilitate the XSL Transformation of XML Docutils into Atom Syndication Format with a designated XSLT stylesheet. Yet, I stil do not realize the reason for your comment. Is ityour comment, an explanatory comment or a comment that my rST documents have issues? > > > Do you mean that the use of multiple lines in which each semicolon > > segregates "title" and "address" is not to be considered as > > standard? > > It could be considered as CSV-variant. You would have to > > * document/motivate the use of this CSV variant > in the preamble fields of an rST document and > * write your own parser (or XSLT extraction rules) > to parse the raw field content.¹ > If I would produce CSV, then I would use my own parser, as I think that XSLT only works with JSON and XML, and probably other formats that can be queried. Nevertheless, I think that I realize your answer. > Also, the semicolon clashes with rST syntax in "authors" fields: > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors > Thank you for this additional information. I will act upon this in a few hours. > ¹ rST supports CSV with the "CSV-table" directive > (and the separator defaulting to ","). > https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table > > Howver, you won't like to write:: > > :authors: .. csv-table:: > I apologise for asking this again, I think, yet I want to be certain. Is this fine to write this? (comma) .. author: BabylonObserver.com , https://babylonobserver.com The Babylon Observer , mailto:in...@ba... Or would it be appropriate to write this? (greater > and lesser < than) .. author: BabylonObserver.com <https://babylonobserver.com> The Babylon Observer <mailto:in...@ba...> > > > >> > I think that it would be nice for Docutils to have features for > >> > XML. > > >> If you want XML, you may try the docutils-XML writer -- Docutils > >> XML is a well defined XML format. > > >> It should be possible to generate HTML from Docutils XML with XSLT > >> styles. This could be a way to achieve a HTML variant that is > >> impossible via the Docutils HTML writers (but is lots of work). > > > > This is interesting. > > > Then, it is possible to utilize an XSLT stylesheet to transform that > > XML to Atom Syndication Format, and an additional XSLT stylesheet to > > transform that XML to HTML; > > > Docutils XML > (XSLT) > Atom > > > Docutils XML > (XSLT) > HTML > > > Of course, it is also possible to utilize the current stylesheet > > which already transforms Atom to HTML. > > > Docutils XML > (XSLT) > Atom > (XSLT) > HTML > > > I'd try to re-use as much as possible. So, you advise to use the standard of Docutils instead of information that may be related to Atom or otherwise, are yes? > Atom is XML with the content embedded as HTML, > so maybe: > > * rST > (Rivista) > rST-preamble + rST-content > > * rST-preamble > (Docutils) > Docutils-XML > rST-content > (Docutils) > HTML > This is what I currently do, and intend to further finalize. rST-preamble > (Docutils) > Atom-dict (title, summary, link, etc.) rST-content > (Docutils) > HTML > Atom-dict (content) Atom-dict > Atom-XML > * XML-preamble + HTML-content (XSLT) > Atom-XML > I think that I would have to merge the XML-preamble and HTML-content, in order to be able to produce an Atom-XML. > * Atom > (XSLT) > HTML > This procedure is already done. # Generate HTML of Atom filepath_xslt_atom = os.path.join( publish_properties.directory_xslt, filename_xslt) atom_as_element_tree = ParserXml.create_element_tree_from_file( filepath_atom) atom_html_as_str = ParserXslt.transform_data( atom_as_element_tree, filepath_xslt_atom) filepath_atom_html = os.path.join( directory_html, directory, identifier, "index.html") with open(filepath_atom_html, "w") as fn: fn.write(atom_html_as_str) > > Günter > Schimon |
From: Schimon J. <sc...@fe...> - 2025-10-09 13:40:09
|
Guenter. Good evening. On Thu, 9 Oct 2025 11:44:01 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > > On Thu, 9 Oct 2025 Guenter Milde via Docutils-users wrote: > >> On 2025-10-08, Schimon Jehudah via Docutils-users wrote: > ... > > >> You should decide, whether the preamble/metadata block should be > >> parsed as reStructuredText (rST) at all or be a different format > > > >> If you decide to use rST for the metadata, you can split off the > >> preamble and parse it to Docutils-XML which then can be converted > >> to Atom Syndication Format with XSLT. > > > Is there example code? > > Not directly. > > It also depends on how you would like to split the preamble from > the content > > * with a pre-processor from the rST file > * after parsing, from the Python "doctree" object > * with XSLT from the Docutils-XML > Fine. So, I suppose, that it is for me to decide. It is just that semicolons should not be utilized, but commas. > >> An alternative idea would be using "yaml", [...] > > > No. I am interested in utilizing only rST. It appears to be a > > perfect format for documents, presentations, and internet pages. > > > >> ... > > >> > Concerning to field "authors"; I have deliberately added > >> > semicolon as it it easier to "split" title from address. > > >> I strongly recommend using an existing standard format. > > > The purpose of Rivista Voyager is to only utilize standards. > > ... > > > I would appreciate example code for hte extraction of "title" and > > "address". > > > Please see fields of the new version of that document. > > Please provide a **minimal** example. > (e.g. input to generate something like > https://en.wikipedia.org/wiki/Atom_(web_standard)#Example_of_an_Atom_1.0_feed) > Pardon. I do not realize what is this for, unless you mean that by "standard" I should comply with the fields (XML elements) of The Atom Syndication Format. Please read further at the end of this message. Otherwise, I handle Atom Syndication Format by collecting rST properties, and contents into a dictionary (i.e. "dict") which is then delivered to function "ParserAtom.document" for further processing into an Atom Syndication Format file. > > ... > > > .. authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message > > .. date: 2025-07-14 00:00:00 UTC > > .. description: Publishing client software for XMPP. > > .. link: xmpp > > .. microsummaries: > > 5 XMPP publishing client software ; projects > > 1 XMPP publishing client software ; desktop > > 4 XMPP publishing client software ; html > > 1 XMPP publishing client software ; mobile > ... > > If you convert the preamble to a rST bibliography:: > > :authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message > :date: 2025-07-14 00:00:00 UTC > :description: Publishing client software for XMPP. > :link: ... > > with a suitable rST construct instead of the non-standard ";",¹ > and run rst2xml on it, you see the XML representation. > I think, that there is no difference to me, because it appears that the output would be just the same with semicolon. However, I will replace all instances of semicolon by comma, for the sake of standards compliancy. NOTE: It means, that the system would have to reject attempts to incorporate commans into Microsummaries, Names and Titles. This field. .. authors: BabylonObserver.com , https://babylonobserver.com The Babylon Observer , mailto:in...@ba... Is realized to this code. <comment xml:space="preserve">author: BabylonObserver.com , https://babylonobserver.com The Babylon Observer , mailto:in...@ba...</comment> The same for field tags. .. tags: Analyses, Currency, Economics, Finance, Fund, Garden, Industry, Metaphor, Mystery Paper, Power, World <comment xml:space="preserve">tags: Analyses, Currency, Economics, Finance, Fund, Garden, Industry, Metaphor, Mystery Paper, Power, World</comment> > How to extract/convert this to atom XML is left as exercise to the > reader. > > Regards, > Günter > > > ¹ In rST, the format for data entries is a "field list" or a > description list. > What to use depends on the context and may be discussed later on a > *minimal* example with corresponding Atom element (one item at a > time). > I think that I, now, realize what you mean. If I correctly realize what you mean, by recommending to comply with standards, then this is what I am intending to do. I intend to remove fields that are not of The Atom Syndication Format, such as "category", or rename other fields to comply with The Atom Syndication Format, such as renaming "slug" to "id", "tags" to "categories", "date" to "published", and add more fields such as "updated". However, fields "metalinks" and "microsummaries" are not part of The Atom Syndication Format. When you imply to correspond with standard, does it mean that you advise to remove fields "metalinks" and "microsummaries" from rST and utilize external files (e.g. TOML) to handle those custom fields? Field "comments" is also not standard; it is a setting to enable comments, so it would have to be removed also. NOTE: The fields of "metalinks" and "microsummaries" are realized into element "atom:link", metalinks into rel="enclosure" and microsummaries into rel="microsummary". Additionally, The Atom Syndication Format allows to be extended, but I do not extend it. https://rfc-editor.org/rfc/rfc4287#section-6 Thinking of this further, I wonder whether I should replace fields "enclosures" and "related" (both are realized as "atom:link") by field "link", and add a new field for "rel". .. links: Mystery Paper Documentary Series , https://babylonobserver.com/mystery-paper/, rel The Babylon Observer , https://babylonobserver.com, rel Mystery Paper – Episode 4 – The Decolonisation Show , /movies/Mystery.Paper.S01.E04.mkv, enclosure Recent episode: #4 – The Decolonisation Show , recent-episode , microsummary As seen, this does not appear to allow me to selectively generate Metalinks, so I would have to generate Metalinks to all local files, I suppose. This is fine, yet this is when I would have to utilize a mean which be external to rST (e.g. TOML). Regards, Schimon |
From: Guenter M. <mi...@us...> - 2025-10-09 12:49:10
|
On 2025-10-09, Schimon Jehudah via Docutils-users wrote: >> What I am missing, is a user documentation. > There is no documentation yet. This software is subjected to further > development. It helps to write/update user documentation in parallel (at least a stub): If the implementation is hard to explain, it's a bad idea. If the implementation is easy to explain, it may be a good idea. -- python -m this >> Also, I cannot find a description of the input format. >> The preamble seems to use no standard but a home-grown syntax that >> looks confusingly similar to reStructuredtext directives. > How so? :: .. title: My simple example .. title:: My simple example Convert with rst2xml and rst2html to see the difference. > Do you mean that the use of multiple lines in which each semicolon > segregates "title" and "address" is not to be considered as standard? It could be considered as CSV-variant. You would have to * document/motivate the use of this CSV variant in the preamble fields of an rST document and * write your own parser (or XSLT extraction rules) to parse the raw field content.¹ Also, the semicolon clashes with rST syntax in "authors" fields: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors ¹ rST supports CSV with the "CSV-table" directive (and the separator defaulting to ","). https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table Howver, you won't like to write:: :authors: .. csv-table:: >> > I think that it would be nice for Docutils to have features for >> > XML. >> If you want XML, you may try the docutils-XML writer -- Docutils XML >> is a well defined XML format. >> It should be possible to generate HTML from Docutils XML with XSLT >> styles. This could be a way to achieve a HTML variant that is >> impossible via the Docutils HTML writers (but is lots of work). > This is interesting. > Then, it is possible to utilize an XSLT stylesheet to transform that > XML to Atom Syndication Format, and an additional XSLT stylesheet to > transform that XML to HTML; > Docutils XML > (XSLT) > Atom > Docutils XML > (XSLT) > HTML > Of course, it is also possible to utilize the current stylesheet which > already transforms Atom to HTML. > Docutils XML > (XSLT) > Atom > (XSLT) > HTML I'd try to re-use as much as possible. Atom is XML with the content embedded as HTML, so maybe: * rST > (Rivista) > rST-preamble + rST-content * rST-preamble > (Docutils) > Docutils-XML rST-content > (Docutils) > HTML * XML-preamble + HTML-content (XSLT) > Atom-XML * Atom > (XSLT) > HTML Günter |
From: Guenter M. <mi...@us...> - 2025-10-09 11:44:18
|
On 2025-10-09, Schimon Jehudah via Docutils-users wrote: > On Thu, 9 Oct 2025 Guenter Milde via Docutils-users wrote: >> On 2025-10-08, Schimon Jehudah via Docutils-users wrote: ... >> You should decide, whether the preamble/metadata block should be >> parsed as reStructuredText (rST) at all or be a different format >> If you decide to use rST for the metadata, you can split off the >> preamble and parse it to Docutils-XML which then can be converted to >> Atom Syndication Format with XSLT. > Is there example code? Not directly. It also depends on how you would like to split the preamble from the content * with a pre-processor from the rST file * after parsing, from the Python "doctree" object * with XSLT from the Docutils-XML >> An alternative idea would be using "yaml", [...] > No. I am interested in utilizing only rST. It appears to be a perfect > format for documents, presentations, and internet pages. >> ... >> > Concerning to field "authors"; I have deliberately added semicolon >> > as it it easier to "split" title from address. >> I strongly recommend using an existing standard format. > The purpose of Rivista Voyager is to only utilize standards. ... > I would appreciate example code for hte extraction of "title" and > "address". > Please see fields of the new version of that document. Please provide a **minimal** example. (e.g. input to generate something like https://en.wikipedia.org/wiki/Atom_(web_standard)#Example_of_an_Atom_1.0_feed) ... > .. authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message > .. date: 2025-07-14 00:00:00 UTC > .. description: Publishing client software for XMPP. > .. link: xmpp > .. microsummaries: > 5 XMPP publishing client software ; projects > 1 XMPP publishing client software ; desktop > 4 XMPP publishing client software ; html > 1 XMPP publishing client software ; mobile ... If you convert the preamble to a rST bibliography:: :authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message :date: 2025-07-14 00:00:00 UTC :description: Publishing client software for XMPP. :link: ... with a suitable rST construct instead of the non-standard ";",¹ and run rst2xml on it, you see the XML representation. How to extract/convert this to atom XML is left as exercise to the reader. Regards, Günter ¹ In rST, the format for data entries is a "field list" or a description list. What to use depends on the context and may be discussed later on a *minimal* example with corresponding Atom element (one item at a time). |
From: Schimon J. <sc...@fe...> - 2025-10-09 10:25:08
|
Greetings. Guenter. On Thu, 9 Oct 2025 09:54:59 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-08, Schimon Jehudah via Docutils-users wrote: > > On Tue, 7 Oct 2025 20:13:23 -0000 (UTC) > > Guenter Milde via Docutils-users wrote: > >> On 2025-10-06, Schimon Jehudah via Docutils-users wrote: > > >> > I forgot to attach the reStructuredText file. > >> ... > > >> > .. authors: LAFKON Publishing ; mailto:ha...@la... > >> > .. category: journal > >> > .. comments: true > >> > .. date: 2004-09-09 0:00:00 UTC > ... > > > Rivista Voyager [...] stores metadata references in Atom > > Syndication Format elements, and XSLT is the only mean to transform > > Atom Syndication Format to XHTML. > > You should decide, whether the preamble/metadata block should be > parsed as reStructuredText (rST) at all or be a different format (I > strongly recommend using an existing standard format). Then document > this for users. > > If you decide to use rST for the metadata, you can split off the > preamble and parse it to Docutils-XML which then can be converted to > Atom Syndication Format with XSLT. > Is there example code? > An alternative idea would be using "yaml", "toml", or some other human > readable data format as container, with only the content using rST. > (Then, the system might even support various content formats > (rST, markdown, XHTML, ...). > No. I am interested in utilizing only rST. It appears to be a perfect format for documents, presentations, and internet pages. > > ... > > > Concerning to field "authors"; I have deliberately added semicolon > > as it it easier to "split" title from address. > > I strongly recommend using an existing standard format. > The purpose of Rivista Voyager is to only utilize standards. I would appreciate example code for hte extraction of "title" and "address". Please see fields of the new version of that document. Fields: "authors", "enclosures", "tags" (title and address), "metalink", "related", and in file "xmpp.rst", see field "microsummaries" and "tags" (some only have address). > > >> ... > > >> > Mail `ha...@la... <mailto:ha...@la...>`_ > > >> This could be simplified, as Docutils recognizes e-mail addresses > >> as standalone hyperlinks (the telephone may also be simplified if > >> you accept a slightly different link text). > >> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks > >> > > > > I am not sure why you wrote it, so I hope that I answer to the > > correct context. > > This is about the credit in the *content* (to be converted to HTML by > Docutils). Here, you can simply write > > Mail ha...@la... > > and Docutils will turn this into an active "mailto" link. Similar for > > Phone tel:+48-816-555-1212 > > but not for gemini: (cf. > https://sourceforge.net/p/docutils/patches/200/). > If this is abount the preamble/metadata, then it is not a concern to me, as I utilize element "atom:link" which data is automatically realize to a hyperlink, even if it is eDonkey2000, Hypercore, et cetera. > ... > > > I further utilize that syntax in the content of a document, yet I am > > lesser fond of that linking syntax, and I would be glad to have an > > additional directive for links. > > > And considering XLink, I would be glad to have something of this > > sort, even if XLink was not a concern. > > > .. link:: > > ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/ > >:text: TrustedComputing_LAFKON_HIGH.mov > > :id: trusted-computing-link > > :class: ed2k-link > > :xlink: ed2k-trusted-computing > > You are free to define and register a "link" directive in your > project. There is some documentation in > https://docutils.sourceforge.io/docs/howto/rst-directives.html > to get you started. > It helps to read the user reference of the standard directives > https://docutils.sourceforge.io/docs/ref/rst/directives.html > especially about "common options" and "common option value types" as > to not re-invent the wheel. (I'd recommend using the established > directive options :name: instead of :id: and :alt: instead of :text:). > > Alternatively, use (in the rST content) some convention for rST, e.g. > > .. class: ed2k-link > .. trusted-computing-link: > > TrustedComputing_LAFKON_HIGH.mov (ed2k__, gnutella__, ...) > > __ > ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/ > __ gnutella://wherever > > or define the targets outside of the (rST) content and use a URI > reference in the document like, e.g. > > Trusted Computing (ed2k__, gnutella__, ...) > > __ #ed2k-trusted-computing > __ #gnutella-trusted-computing>`__ > > (this assumes that the final HTML document contains the targets > with the matching IDs). > I will explore it. > > Regards, > > Günter > Thank you, Schimon |
From: Guenter M. <mi...@us...> - 2025-10-09 09:55:15
|
On 2025-10-08, Schimon Jehudah via Docutils-users wrote: > On Tue, 7 Oct 2025 20:13:23 -0000 (UTC) > Guenter Milde via Docutils-users wrote: >> On 2025-10-06, Schimon Jehudah via Docutils-users wrote: >> > I forgot to attach the reStructuredText file. >> ... >> > .. authors: LAFKON Publishing ; mailto:ha...@la... >> > .. category: journal >> > .. comments: true >> > .. date: 2004-09-09 0:00:00 UTC ... > Rivista Voyager [...] stores metadata references in Atom > Syndication Format elements, and XSLT is the only mean to transform > Atom Syndication Format to XHTML. You should decide, whether the preamble/metadata block should be parsed as reStructuredText (rST) at all or be a different format (I strongly recommend using an existing standard format). Then document this for users. If you decide to use rST for the metadata, you can split off the preamble and parse it to Docutils-XML which then can be converted to Atom Syndication Format with XSLT. An alternative idea would be using "yaml", "toml", or some other human readable data format as container, with only the content using rST. (Then, the system might even support various content formats (rST, markdown, XHTML, ...). ... > Concerning to field "authors"; I have deliberately added semicolon as > it it easier to "split" title from address. I strongly recommend using an existing standard format. >> ... >> > Mail `ha...@la... <mailto:ha...@la...>`_ >> This could be simplified, as Docutils recognizes e-mail addresses as >> standalone hyperlinks (the telephone may also be simplified if you >> accept a slightly different link text). >> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks > I am not sure why you wrote it, so I hope that I answer to the correct > context. This is about the credit in the *content* (to be converted to HTML by Docutils). Here, you can simply write Mail ha...@la... and Docutils will turn this into an active "mailto" link. Similar for Phone tel:+48-816-555-1212 but not for gemini: (cf. https://sourceforge.net/p/docutils/patches/200/). ... > I further utilize that syntax in the content of a document, yet I am > lesser fond of that linking syntax, and I would be glad to have an > additional directive for links. > And considering XLink, I would be glad to have something of this sort, > even if XLink was not a concern. > .. link:: ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/ >:text: TrustedComputing_LAFKON_HIGH.mov > :id: trusted-computing-link > :class: ed2k-link > :xlink: ed2k-trusted-computing You are free to define and register a "link" directive in your project. There is some documentation in https://docutils.sourceforge.io/docs/howto/rst-directives.html to get you started. It helps to read the user reference of the standard directives https://docutils.sourceforge.io/docs/ref/rst/directives.html especially about "common options" and "common option value types" as to not re-invent the wheel. (I'd recommend using the established directive options :name: instead of :id: and :alt: instead of :text:). Alternatively, use (in the rST content) some convention for rST, e.g. .. class: ed2k-link .. trusted-computing-link: TrustedComputing_LAFKON_HIGH.mov (ed2k__, gnutella__, ...) __ ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/ __ gnutella://wherever or define the targets outside of the (rST) content and use a URI reference in the document like, e.g. Trusted Computing (ed2k__, gnutella__, ...) __ #ed2k-trusted-computing __ #gnutella-trusted-computing>`__ (this assumes that the final HTML document contains the targets with the matching IDs). Regards, Günter |
From: Schimon J. <sc...@fe...> - 2025-10-09 09:47:10
|
Good afternoon. On Thu, 9 Oct 2025 08:53:15 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-07, Schimon Jehudah via Docutils-users wrote: > > > > >> Can you provide a **minimal** working example of what you want > > > >> to achieve? > > > > > > > Yes. I can. > > > > > > > I am working on a publication platform of which all produced > > > > documents are XML (Atom Syndication Format), and these documents > > > > are transformed to XHTML with XSLT stylesheets. > > > > > > How do you produce the XML (Atom) documents? > > > With a custom Docutils writer or with XSLT from a standard output > > > format? > > > The system produces and Atom Syndication Format document, which > > receives the XHTML data from Docutils; Docutils converts *only the > > content* to XHTML. > > Then it may be cleaner to strip the preamble and feed Docutils only > the content. Currently, the preamble turns up as redundant comment in > the output bloating both, generated atom and HTML files. > Yes. So I noticed. I will explore a solution. > > > The process can be observed at. > > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/publish/xhtml.py > > > > > Docutils conversion. > > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/utility/document.py > > > > > Atom formation. > > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/parser/atom.py > > > > What I am missing, is a user documentation. > There is no documentation yet. This software is subjected to further development. > Also, I cannot find a description of the input format. The preamble > seems to use no standard but a home-grown syntax that looks > confusingly similar to reStructuredtext directives. > How so? Do you mean that the use of multiple lines in which each semicolon segregates "title" and "address" is not to be considered as standard? > > > I think that it would be nice for Docutils to have features for > > XML. > > If you want XML, you may try the docutils-XML writer -- Docutils XML > is a well defined XML format. > > It should be possible to generate HTML from Docutils XML with XSLT > styles. This could be a way to achieve a HTML variant that is > impossible via the Docutils HTML writers (but is lots of work). > This is interesting. Then, it is possible to utilize an XSLT stylesheet to transform that XML to Atom Syndication Format, and an additional XSLT stylesheet to transform that XML to HTML; Docutils XML > (XSLT) > Atom Docutils XML > (XSLT) > HTML Of course, it is also possible to utilize the current stylesheet which already transforms Atom to HTML. Docutils XML > (XSLT) > Atom > (XSLT) > HTML > The easy way to get XHTML is using the "html4css1" or the "html5" > writer. Both generate HTML complying to the respective standards that > is also valid XML (polyglot HTML). > Thank you. > Regards, > Günter > Best, Schimon |
From: Guenter M. <mi...@us...> - 2025-10-09 08:53:31
|
On 2025-10-07, Schimon Jehudah via Docutils-users wrote: > > >> Can you provide a **minimal** working example of what you want to > > >> achieve? > > > > > Yes. I can. > > > > > I am working on a publication platform of which all produced > > > documents are XML (Atom Syndication Format), and these documents > > > are transformed to XHTML with XSLT stylesheets. > > > > How do you produce the XML (Atom) documents? > > With a custom Docutils writer or with XSLT from a standard output > > format? > The system produces and Atom Syndication Format document, which > receives the XHTML data from Docutils; Docutils converts *only the > content* to XHTML. Then it may be cleaner to strip the preamble and feed Docutils only the content. Currently, the preamble turns up as redundant comment in the output bloating both, generated atom and HTML files. > The process can be observed at. > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/publish/xhtml.py > Docutils conversion. > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/utility/document.py > Atom formation. > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/parser/atom.py What I am missing, is a user documentation. Also, I cannot find a description of the input format. The preamble seems to use no standard but a home-grown syntax that looks confusingly similar to reStructuredtext directives. > I think that it would be nice for Docutils to have features for XML. If you want XML, you may try the docutils-XML writer -- Docutils XML is a well defined XML format. It should be possible to generate HTML from Docutils XML with XSLT styles. This could be a way to achieve a HTML variant that is impossible via the Docutils HTML writers (but is lots of work). The easy way to get XHTML is using the "html4css1" or the "html5" writer. Both generate HTML complying to the respective standards that is also valid XML (polyglot HTML). Regards, Günter |
From: Schimon J. <sc...@fe...> - 2025-10-09 07:37:16
|
Thank you for your helpful respond. Schimon On Thu, 9 Oct 2025 07:25:29 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-07, Schimon Jehudah via Docutils-users wrote: > > On Tue, 7 Oct 2025 18:41:51 -0000 (UTC) > > Guenter Milde via Docutils-users wrote: > >> On 2025-10-06, Schimon Jehudah via Docutils-users wrote: > >> >> On 2025-09-28, Schimon Jehudah via Docutils-users wrote: > > >> >> > XLink might be helpful for both, Atom and (X)HTML, in order to > >> >> > set accurate links to references. > > >> I don't think using XLink will give advantages to (X)HTML, as > >> browser support is missing. > ... > > > XLink is fine to them, for toying with SVG ... > > Sorry for beeing ambiguous. My response was intended to mean: > > I don't think using XLink will give advantages to > *Docutils (X)HTML writers*, > as it XLink is not part of the various HTML standards > and browser support is missing. > > > > Also, XLink has no format of its own, and it is meant to be > > incorporated into existing formats. > > As docutils.dtd is designed for extensibility, it should be easy > for interested parties to derive a custom document type with, e.g., > a <link> element supporting XLink syntax. > > > Günter > |
From: Guenter M. <mi...@us...> - 2025-10-09 07:25:42
|
On 2025-10-07, Schimon Jehudah via Docutils-users wrote: > On Tue, 7 Oct 2025 18:41:51 -0000 (UTC) > Guenter Milde via Docutils-users wrote: >> On 2025-10-06, Schimon Jehudah via Docutils-users wrote: >> >> On 2025-09-28, Schimon Jehudah via Docutils-users wrote: >> >> > XLink might be helpful for both, Atom and (X)HTML, in order to >> >> > set accurate links to references. >> I don't think using XLink will give advantages to (X)HTML, as browser >> support is missing. ... > XLink is fine to them, for toying with SVG ... Sorry for beeing ambiguous. My response was intended to mean: I don't think using XLink will give advantages to *Docutils (X)HTML writers*, as it XLink is not part of the various HTML standards and browser support is missing. > Also, XLink has no format of its own, and it is meant to be > incorporated into existing formats. As docutils.dtd is designed for extensibility, it should be easy for interested parties to derive a custom document type with, e.g., a <link> element supporting XLink syntax. Günter |
From: Schimon J. <sc...@fe...> - 2025-10-08 05:04:39
|
Good day. As I am currently discussing with Mr. Guenter Milde about XLink and the system of the publishing platform "Rivista Voyager" (CMS and SSG), I do want to advise for Docutils to support The Atom Syndication Format. The Atom Syndication Format is standard, and has the capabilities to transfer the whole internet into an API oriented internet, by having XML for publications instead of (broken) HTML. This means, that documents that are conveyed as Atom Syndication Format can be interacted with any device, as small as an OGG/MP3 Player which has a software for parsing XML and HTML, and without the need for a visual display screen monitor. > It is important to state that because Rivista Voyager, as an > ACE-compliant publication platform, is a machine-readable site, due > to the predicted and structured form of The Atom Syndication Format, > it is possible to interact and communicate with Rivitsa Voyager by > audible directives and without a display screen monitor, utilizing > portable devices with software such as eSpeak and Numen Voice Control. > > -- A new hope for further internet federation via HTTP Please read these resources. https://journal.woodpeckersnest.eu/about/rivista/ https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/about/rivista.rst gemini://woodpeckersnest.space/~schapps/journal/2025-07-29-announcing-ace.gmi gemini://woodpeckersnest.space/~schapps/journal/2025-08-10-an-analyses-of-the-benefits-of-ace.gmi gemini://woodpeckersnest.space/~schapps/journal/2025-10-08-a-hope-for-further-internet-federation-via-http.gmi I have been experimenting with The Atom Syndication Format for a couple of months or so, and I have managed to create a whole CMS site with just Atom Syndication Format files, including forms and pages of contact, comments, and search. I urge you to examine the resulted documents of command "rivista-build" (be sure to start "rivista-adjust" before that), and be inspired to consider and add The Atom Syndication Format as an option of Docutils. For Atom Syndication Format documents with navigation links, please refer to these documents. https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/1270-01-01-an-introduction-to-havamal.rst https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/2024-08-01-establish-your-i2p-site-in-five-minutes.rst The element "atom:link" is also utilized to realize resources of reStructuredText bibliography and metadata. Kind regards, Schimon |
From: Schimon J. <sc...@fe...> - 2025-10-08 04:20:37
|
Guenter. Good day. On Tue, 7 Oct 2025 20:13:23 -0000 (UTC) Guenter Milde via Docutils-users <doc...@li...> wrote: > On 2025-10-06, Schimon Jehudah via Docutils-users wrote: > > > I forgot to attach the reStructuredText file. > ... > > > .. authors: LAFKON Publishing ; mailto:ha...@la... > > .. category: journal > > .. comments: true > > .. date: 2004-09-09 0:00:00 UTC > > ... > > There are actually 2 ways to specify meta-data in rST, so you don't > need to resort to comments: > > a) bibliographic fields (for "visible" metadata) > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields > > A "visible" document start could look like:: > > a short animated video about computers and trust > ------------------------------------------------ > > :author: LAFKON Publishing <ha...@la...> > :author: `LAFKON Publishing <mailto:ha...@la...>`__ > :abstract: > This is a short animated video (3:30 minutes) about computers > and trust. “Trusted Computing” - ever heard of it? > This motion graphic style documentary explains what the term > “trust” has in common with “Trusted Computing” and where you will > meet this so-called technology in the near future. > Computers and Internet gave you freedom. TCPA is designed > against freedom! It is crucial that you listen to it. > > :date: 2004-09-09 0:00:00 UTC > :slug: 2004-09-09-trusted-computing-2004 > :tags: control, computing, iot, lafkon, lagrande, > :type: text > This is interesting, and it might be helpful to me. Thank you. > b) the "meta" directive (for "invisible" metadata) > https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata > > Example:: > > .. meta:: > :authors: LAFKON Publishing <mailto:ha...@la...> > :category: journal > :comments: true > :date: 2004-09-09 0:00:00 UTC > :description: > :slug: 2004-09-09-trusted-computing-2004 > :tags: control, computing, iot, lafkon, lagrande, > :type: text > > Both can be combined. > I did not know of it; yet, that is probably not useful for project Rivista Voyager, because it stores metadata references in Atom Syndication Format elements, and XSLT is the only mean to transform Atom Syndication Format to XHTML. Tags are placed inside element "atom:category", and XSLT stylesheet extracts values of "atom"categories" to (X)HTML metadata. <xsl:if test="atom:category"> <xsl:element name="meta"> <xsl:attribute name="name"> <xsl:text>keywords</xsl:text> </xsl:attribute> <xsl:attribute name="content"> <xsl:for-each select="atom:category"> <xsl:value-of select="@term"/> <xsl:text>, </xsl:text> </xsl:for-each> </xsl:attribute> </xsl:element> </xsl:if> View the source code of these documents (XML and HTML). This is Atom (XSLT: client-side) https://journal.woodpeckersnest.eu/posts/2004-09-09-trusted-computing-2004/index.atom This is HTML (XSLT: server-side) https://journal.woodpeckersnest.eu/posts/2004-09-09-trusted-computing-2004/index.html Additionally, as element "atom:category" provides attribute "label", the reStructuredText tags field will be designed as. .. tags: BitTorrent ; bittorrent eDonkey2000 ; ed2k Gnutella ; gnutella IPFS ; ipfs Linux ; linux MUTE; mute ReactOS ; reactos Concerning to field "authors"; I have deliberately added semicolon as it it easier to "split" title from address. .. authors: LAFKON Publishing ; mailto:ha...@la... > ... > > > .. title: Trusted Computing (2004) > > Besides the "visible" title (via first section) > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title > there is also the "invisible" title via directive: > https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title > I did not know of it. I will explore this concern. > ... > > > .. image:: https://lafkon.net/work/trustedcomputing.jpg > > :alt: Trusted Computing > > :loading: lazy > > :target: https://lafkon.net/work/trustedcomputing.jpg > > :width: 100% > > The "target" option is intended for cases where you want to use an > image as link like:: > > .. image:: restructuredtext.svg > :alt: reStructuredText > :target: https://docutils.sourceforge.io/rst.html > Yes. I did so for G2DN https://g2.doxu.org https://journal.woodpeckersnest.eu/posts/2026-01-01-gnutella2-and-internet-publications/ https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/2026-01-01-gnutella2-and-internet-publications.rst > You may also use it to get a standalone image or an image from a > thumbnail In most cases, there is no need to repeat the image URI as > "target". > Thank you. I intend to do this. > ... > > > Mail `ha...@la... <mailto:ha...@la...>`_ > > This could be simplified, as Docutils recognizes e-mail addresses as > standalone hyperlinks (the telephone may also be simplified if you > accept a slightly different link text). > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks > I am not sure why you wrote it, so I hope that I answer to the correct context. For most links, I resort to element "atom:link" which is handled by the software which handles Atom Syndication Format documents; in this case, the XSLT stylesheet is a software which handles those links for me. I did so with Hypercore and IPFS URIs. https://journal.woodpeckersnest.eu/help/gemini/ https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/help/gemini.rst I further utilize that syntax in the content of a document, yet I am lesser fond of that linking syntax, and I would be glad to have an additional directive for links. And considering XLink, I would be glad to have something of this sort, even if XLink was not a concern. .. link:: ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/ :text: TrustedComputing_LAFKON_HIGH.mov :id: trusted-computing-link :class: ed2k-link :xlink: ed2k-trusted-computing > > Günter > > Regards, Schimon |