[Clfs-dev] I Would like to modify the clfs-embedded book but I got an error

[Ken Moffat]

On Fri, Mar 22, 2024 at 09:31:47AM +0100, Michele Bucca wrote:
> Hello Everyone.
> 
> I would like to update the clfs-embedded book since it has not been updated
> in years. I've tried to modify the docbook source but I get this error when
> I try to compile it:
> 
> Validating x86 book...
> /Volumes/projects/clfs-embedded-next/BOOK/x86-index.xml:19: element
> variablelist: Relax-NG validity error : Expecting an element caution, got
> nothing
> /Volumes/projects/clfs-embedded-next/BOOK/x86-index.xml:19: element
> variablelist: Relax-NG validity error : Element sect1 has extra content:
> variablelist
> /Volumes/projects/clfs-embedded-next/BOOK/x86-index.xml:8: element sect1:
> Relax-NG validity error : Expecting element toc, got sect1
> /Volumes/projects/clfs-embedded-next/BOOK/x86-index.xml:8: element sect1:
> Relax-NG validity error : Element chapter has extra content: sect1
> materials/chapter.xml:8: element chapter: Relax-NG validity error :
> Expecting element toc, got chapter
> /Volumes/projects/clfs-embedded-next/BOOK/x86-index.xml fails to validate
> Makefile:60: recipe for target 'x86-validate_dump-xml' failed
> make[2]: *** [x86-validate_dump-xml] Error 3
> Makefile:71: recipe for target 'x86-profiled-xml' failed
> make[1]: *** [x86-profiled-xml] Error 2
> Makefile:84: recipe for target 'x86-html' failed
> make: *** [x86-html] Error 2
> 
> I don't know how to troubleshoot it, to me it seems that there isn't any
> error in the syntax. I've changed the version of the packages to the most
> recent ones (Used in LFS 12.1, updated dropbear, busybox and musl), changed
> the links to download the packages and updated the changeslog.
> 
> Can Anyone give me advice? Should I upload the source online and send you a
> link? I'm currently using my own git repo stored locally.
> 
> Michele Bucca

Hi Michele,

it's a long time since I looked at CLFS, and I don't think I've any
experience with Relax-NG.  But from current editing on BLFS I can
tell you that manually editing docbook can be a pain in the
proverbial when validation fails.  Sometimes a "simple" change can
take me hours to "fix", on at least one recent item I gave up trying
to label soemthing as a directory and just kept it as plain text in
the note, with a comment above it in the XML that I could not make
it pretty.

The first error is what matters, line 19 of x86-index.xml.  The
validator thinks something is missing - maybe in that line, or maybe
just before it.  As with many programming languages, after one error
whatever errors follow might be spurious.

If you review that file and are convinced you have not missed
anything (maybe look at other unchanged arch-index.xml files), the
only advice I can give is to comment out parts of the change until
you (with luck) find what causes the problem.  Sometimes the DTD
will not let you add things (e.g. notes) in the item where you think
they belong.

For a change which you think is correct but does not render, and
therefore you cannot review how it actually looks, perhaps use git
stash push, create a new temporary branch, change to that branch,
git stash pop.  Then comment out or delete the first problem until
that page renders, making a note of what you commented, and repeat
for any other problems.  Then go back and look at what you have
commented.

Occasionally when I've done that in the past for BLFS I eventually
think 'oh, yes, silly me!' although after a few hours of tearing my
hair out I tend to use stronger language :)

For small changes, I now often try to render a page several times
before making a commit.  When you are making a major overhaul I
realise that might not be practical.  But if you can go with
changing individual pages, or packages, per commit (and getting it
to render for each commit), that can be a way of getting towards a
usable result.  Until the final commit, the book can be regarded as
'development', and then with the final commit you get a usable
result.

But as to updating the CLFS book, I don't know if anybody is around
who can do that.  If not, you might need to fork it and upload it
somewhere.  For a rendered book, that probably means buying
webspace.

HTH

ĸen
-- 
Is it hard?  Not if you have the right attitudes. Its having the
right attitudes thats hard.
 -- Robert M. Pirsig, Zen and the Art of Motorcycle Maintenance.