[Cuis-dev] EruditeXMLBook example

[H. Hirzel]

Hi Mariano

Thank you for implementing a first version of an EruditeXMLBook class 
and supporting code. I think to base the XML representation of Erudite 
books on an extension of (X)HTML a very exiting approach as it offers 
vast possibilities.

The fact that you could implement this so quickly after the DocBook 
discussion earlier this week demonstrates that you have a good, 
extensible structure in the Erudite documentation system code base.

As it is about extending HTML in a way that  Smalltalk features may be 
loaded and executable code may be marked, I think it needs some 
discussion what the options are and how this should be done in particular.

Using (X)HTML makes use of an standard which has been around for a long 
time and people know. This is a huge benefit, this should give a reason 
for acceptance of the approach.  It should result in a small additional 
learning effort for the Erudite/Smalltalk oriented features. It is also 
good for generated XML content files. Compared to this DOCBook is not 
well-known and as you noted can not be easily extended. XHTML can also 
benefit from conversion programs like pandoc (with some post-editing 
afterwards) and thus get content from various sources.

Regarding your XML code example in particular:

I would drop the request that each section needs to be in a separate 
file as it is the case with the 'book.xml' in DocBook. So it should also 
be possible to create a Erudite book from one XHTML file.

As an Erudite book is composed of sections I would not use a <chapter> 
tag but <section> instead. This is a tag in the XHTML standard. Sections 
may also be nested thus giving an easy way to specify subsections which 
Erudite supports. I am not aware if nesting sections works for DocBook. 
So the test example should include more than one section.

Going for known tags also applies for <title> tag, I suggest just to use 
<h1> for the whole book <h2>, <h3>... within the sections.

I have seen that EruditeDoc nodes also have a data property. But I have 
not observed yet where they are used. Could the data attribute 
(containing sometimes a dictionary object) be used for attributes of 
XHTML tags? The YAXO XML reader supports attributes.

As for the Smalltalk code representation I want to conduct some tests 
with EruditeXMLBook and give a more detailed comment later.

Kind regards

Hannes


On 13/03/2025 11:45 pm, Mariano Montone wrote:
>
> Hi Hannes, folks,
>
> El 12/3/25 a las 12:00, H. Hirzel escribió:
>> On 11/03/2025 3:28 pm, Mariano Montone via Cuis-dev wrote:
>>
>>> Btw, last time I looked at DocBook, I didn't find it extensible the 
>>> way I would have liked.
>>>
>>> In my opinion, we should have an XML standard that is easily 
>>> extensible, and that completely separates semantic elements from its 
>>> rendering.
>>>
>>> That would make it possible to manipulate documents and extract 
>>> information from them in a powerful way, without losing information. 
>>> And also render the documents for different mediums in a correct way.
>>>
>>> I don't understand why there's not something like that. I don't 
>>> think DocBook is that, but it should have been.
>> Could you please elaborate on this? For my purposes it seems to be 
>> good enough. Or do you specifically mean the handling of the embedded 
>> code expressions?
>>>
>>> That's what XMLEruditeBook is about. 
>
> I've added an example of XML books.
>
> To try, evaluate:
>
> Feature require: 'EruditeXMLBook'.
>
> (EruditeXMLBook new
>      file: (CodePackage installedPackages at: 'EruditeXMLBook') fullFileName asFileEntry parent // 'Examples/xmlbook2.xml')
>      open.
>
> This is the demo book:
>
> <book>
>    <requirements>
>      <feature>EruditeXMLBookHTML</feature>
>      <feature>EruditeXMLBookSmalltalk</feature>
>    </requirements>
>    <chapter>
>      <title>Intro</title>
>      <p>Hello world</p>
>      <p>
>        <ul>
>          <li>Hello</li>
>          <li>World</li>
>        </ul>
>      </p>
>      <p>
>        <smalltalk>
>          Object new
>        </smalltalk>
>      </p>
>      <p>
>        <doit>
>          Smalltalk inspect
>        </doit>
>      </p>
>    </chapter>
> </book>
>
> Notice how the book specifies the features it needs for parsing and 
> rendering, and they are loaded when the book is opened.
>
> XML makes the syntax automatically extensible, and references to the 
> requirements loads the parsers and renderers needed for a book.
>
> There's no book that can't be authored with a system like this! :)
>
> This is Erudite endgame :P
>
>       Mariano
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20250315/4ac1df2f/attachment.htm>