[Cuis-dev] Erudite Help file system for Cuis -> Can it read Docbook files? PetitParser version?

[H. Hirzel]

Hi Mariano

Thanks for the information that

a) subclasses of EruditeBook or more specifically DocBookEruditeBook 
determine what is shown in the 'Read' submenu of the 'Erudite' menu.

b) that the #initialize method of the book class has to make sure that 
the book code may be found.

With this I managed to load the Docbook version of TheCuisManual

DocBookEruditeBook subclass: #TheCuisBook
     instanceVariableNames: ''
     classVariableNames: ''
     poolDictionaries: ''
     category: 'EruditeDocBook-Books'

initialize
"modified by HannesH because

I put this folder 
https://github.com/Cuis-Smalltalk/Erudite/tree/master/DocBook/TheCuisBook 
into the Cuis User files folder.

"
     super initialize.
     self title: 'The Cuis Book'.
     self file:  'TheCuisBook/book.xml' asFileEntry.
     self imageDir: 'TheCuisBook/img' asDirectoryEntry


Equipped with this knowhow I tried a simple example, see below.

The book opened but it was empty.

I guess because the example was too minimal. There are some assumptions 
about the structure of a minimal DocBook file. What are they?

Kind regards

Hannes



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

Minimal Markdown example converted to DocBook

to be parsed by the Erudite DocBook Reader

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

Step1: Create a markdown file

# My Doc Book Test 1
## Introduction
This is a test to find about some minimal features supported by the Cuis 
Erudite Help System.

## Markdown examples

A bullet list

- Buenos Aires
- Johannesburg
- Geneva

A numbered list

1. Identify the gaps
2. Find a solution
3. Implement

## Data conversion
Options for pandoc
````
pandoc --help
````

Markdown to DocBook conversion
````
pandoc -f markdown -t docbook MyDocBookTest1.md -o MyDocBookTest1.xml
````

## Conclusion




Step2a: Convert to DocBook4 with pandoc


pandoc -f markdown -t docbook MyDocBookTest1.md -o MyDocBookTest1.xml


Step2a: Add XML book header

I had to manually add a header because pandoc did not provide that. I 
guess an option for pandoc will solve that.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<book id="MyDocBookTest1.xml" lang="en">
....  <--- insert here the result from the

</book>




Step3: The DocBook XML file: MyDocBookTest1.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<book id="MyDocBookTest1.xml" lang="en">
<sect1 id="my-doc-book-test-1">
   <title>My Doc Book Test 1</title>
   <sect2 id="introduction">
     <title>Introduction</title>
     <para>
       This is a test to find about some the minimal features supported 
by the
       Cuis Erudite Help System.
     </para>
   </sect2>
   <sect2 id="markdown-examples">
     <title>Markdown examples</title>
     <para>
       A bullet list
     </para>
     <itemizedlist spacing="compact">
       <listitem>
         <para>
           Buenos Aires
         </para>
       </listitem>
       <listitem>
         <para>
           Johannesburg
         </para>
       </listitem>
       <listitem>
         <para>
           Geneva
         </para>
       </listitem>
     </itemizedlist>
     <para>
       A numbered list
     </para>
     <orderedlist numeration="arabic" spacing="compact">
       <listitem>
         <para>
           Identify the gaps
         </para>
       </listitem>
       <listitem>
         <para>
           Find a solution
         </para>
       </listitem>
       <listitem>
         <para>
           Implement
         </para>
       </listitem>
     </orderedlist>
   </sect2>
   <sect2 id="data-conversion">
     <title>Data conversion</title>
     <para>
       Options for pandoc
     </para>
     <programlisting>
pandoc --help
</programlisting>
     <para>
       Markdown to DocBook conversion
     </para>
     <programlisting>
pandoc -f markdown -t docbook MyDocBookTest1.md -o MyDocBookTest1.xml
</programlisting>
   </sect2>
   <sect2 id="conclusion">
     <title>Conclusion</title>
     <para>
     </para>
   </sect2>
</sect1>
</book>


Step4. The Cuis DocBook class definition


'From Cuis7.3 [latest update: #7061] on 11 March 2025 at 8:03:31 pm'!
!classDefinition: #MyDocBookTest1 category: #'EruditeDocBook-Books'!
DocBookEruditeBook subclass: #MyDocBookTest1
     instanceVariableNames: ''
     classVariableNames: ''
     poolDictionaries: ''
     category: 'EruditeDocBook-Books'!

!MyDocBookTest1 methodsFor: 'as yet unclassified' stamp: 'hjh 3/11/2025 
19:04:34'!
initialize

     super initialize.

     self title: 'My Doc Book Test 1'.

     self file:  'MyDocBookTest1.xml' asFileEntry.

     "
     self imageDir: 'myDocBookTest1-img'
     "! !

PROBLEM

It does not show because probably the structure is too simple. There are 
some assumptions about a minimal DocBook file in

DocBookEruditeBookStorer>>load

load

     | xml loadedBook |

     "Only the format of one file per chapter is supported for now..."

     loadedBook := book class new
                     file: book file;
                     yourself.
     xml := XMLDOMParser parseDocumentFrom: book file readStream.
     xml tagsNamed: #title do: [:elem | loadedBook title: elem 
contentString].
     "Each include is expected to have a chapter."
     xml tagsNamed: #xi:include do: [:elem | | chapterFilePath 
chapterXML chapterTitle |
         chapterFilePath := book file parent // (elem attributeAt: #href).
         chapterXML := XMLDOMParser parseDocumentFrom: chapterFilePath 
readStream.
         chapterTitle := chapterXML firstTagNamed: #title.
         chapterTitle ifNotNil: [
             loadedBook addSection: chapterTitle contentString contents: 
chapterFilePath textContents]].

     ^ loadedBook