Ticket #923 (assigned enhancement)

Opened 4 years ago

Last modified 3 years ago

Integrate Joe's "simp" changes from main book

Reported by: bradfa Owned by: bradfa
Priority: trivial Milestone: CLFS Standard 3.1.0
Component: BOOK Version: CLFS Standard GIT
Keywords: Cc:

Description

Joe had worked on the 'simp' branch of the main book back in 2011. The goal was to provide a clfs specific schema that would present writing the book in a way that could have common and not-common sections all in one file.

For instance, most of the instructions for building GCC are such that there's a ton of text that's common to all archs. Only some text is specific to which ever arch is being read. Right now we end up with a common file and one file per arch with lots of references back to the common file. This makes reading either the common file or each of the arch's files difficult as seeing how to get from the files to the output is difficult. With Joe's 'simp' changes everything goes in one file and the section that's specific to any arch or another goes inline with indication for which arch it's for. Multiple archs can go together in a block, such as if just one arch is different.

Migration to this new 'simp' style can be done seamlessly based on the last tests I remember Joe doing. As things are converted over they automatically start using the new schemas and validation. Until they get converted, the old just docbook is used.

Change History

comment:1 Changed 4 years ago by bradfa

  • Status changed from new to assigned
  • Owner changed from clfs-commits@… to bradfa

comment:2 Changed 4 years ago by kb0iic

I'd like to start working on this. While we do this, it'd be nice to have the install and make sections userinput remapped to install and make.

Be easier when extracting comands with jHalfs or some other user's scripts and xsl.

Also, this would be easier to work with when updating the systemd branch.

Frankly, we could probably use this with systemd and still have one book! Both sysvinit and systemd. But not sure how complicated it would get when editing heh. We'd need a systemd entity for version and a sysvinit entity for version, possibly.

I will look at it closer. This would be ideal, and get rid of editing so much when doing a simple change.

It will take a lot of editing and some community support to check for errors.

comment:3 Changed 4 years ago by chris@…

I've been working on updating the page for EGLIBC on this branch, but I've run into a problem. There are a bunch of xml tags that seem to have no equivalent with the new schema, which causes the page to fail validation. It complains about not recognizing "&mdash;", "<quote>", "<ulink>", and "<function>", and some others. I don't know what the best solution for this would be, whether to try to include the data from the old docbook code to allow for those tags to work (if this is possible), or create code in the new schema to add them from scratch, or some other possibility.

comment:4 Changed 4 years ago by chris@…

  • Version changed from CLFS Embedded GIT to CLFS Standard GIT
  • Milestone changed from CLFS Embedded 1.0.0 to CLFS Standard 2.2

comment:5 Changed 4 years ago by chris@…

 This thread has additional information on it works.

comment:6 Changed 4 years ago by chris@…

I believe this should be a comprehensive list of every xml tag/entity that is used in the current xml files but not recognized when using the new schema:

&mdash;
<computeroutput>
<function>
<itemizedlist>
<listitem>
<parameter>
<quote>
<ulink>
<variablelist>
<varlistentry>

comment:7 Changed 3 years ago by chris@…

I found this recently -  http://lists.cross-lfs.org/pipermail/clfs-dev-cross-lfs.org/2010-May/000795.html. It was an older attempt by Joe to simplify the XML, using tags called <archentry> and <archopt> which wrap around the existing XML. If I understand correctly, it should mean that all the existing XML code can mostly be used as-is (no need to find ways to re-implement various XML tags as described for the other simp option above), just wrap these new couple of tags around it.

I haven't really been able to test it though, as every time I try to do a validation I get an error about one of the .xsl files not being a stylesheet. Even just using the "go.sh" script included in the attachment in Joe's email, which just renders a very simple example, doesn't work either, so maybe the xsl code used there is just old and needs to be updated...though I wouldn't really know how.

Joe did send a follow-up email to the list a couple months later saying he had given up on this scheme because he thought it made the book to difficult to read. Still, I would like to see if this can be tested, and see how much more difficult it really does make the book to read, if anyone can help get the xsl updated (or just fixed, I'm not sure) for the proposed tags to actually work.

comment:8 Changed 3 years ago by kb0iic

  • Priority changed from major to trivial
Note: See TracTickets for help on using tickets.