Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: point to openjade; provide instructions for Lyx->SGML; provide pointers to Debian packages #40

Open
paravoid opened this issue Dec 2, 2023 · 5 comments
Open

doc: point to openjade; provide instructions for Lyx->SGML; provide pointers to Debian packages #40

paravoid opened this issue Dec 2, 2023 · 5 comments
Assignees
@pbiering
Labels
enhancement
Milestone
4.2.0

Comments

@paravoid
Copy link

paravoid commented Dec 2, 2023

It took me a while to figure out how to regenerate the ipv6calc.html file from the source ipv6calc.lyx file. I'm filing this to document this for others, and perhaps as a feature enhancement request for doc/generate.sh:

This is a two step process: first, the Lyx file is generated to an SGML. Second, the SGML to the HTML. (Note: I have not figured out what the purpose of the XML file in the source tree is.).

Only the second step is actually in generate.sh.

Step 1: Lyx to SGML

  1. apt install lyx docbook-utils
  2. cd doc && lyx --export docbook ipv6calc.lyx

Step 2: SGML to HTML

The build system seems to be using "jade", but this is an old piece of software that has been forked in the meantime. Replacing "jade" with "openjade" seems to work just fine.

  1. apt install opensp openjade docbook docbook-dsssl
  2. cd doc && onsgmls -s ipv6calc.sgml (This is optional and just validates the SGML. ./generate.sh does this)
  3. cd doc && openjade -t sgml -i html -V nochunks -d "ldp.dsl#html" ipv6calc.sgml > ipv6calc.html (./generate.sh does this)

As an alternative:

  1. (as above)
  2. (as above)
  3. apt install ldp-docbook-dsssl
  4. cd doc && openjade -t sgml -i html -V nochunks -d "docbook/stylesheet/dsssl/ldp/ldp.dsl#html" ipv6calc.sgml > ipv6calc.html (in this case, doc/ldp.dsl is not necessary and can be removed)

ldp here stands for "Linux Documentation Project", and the ldp.dsl file is almost a pristine copy compared to the system copy as shipped in the ldp-docbook-dsssl package.

Versions used

This was under a Debian sid with Lyx v2.3.7, Docbook 4.5, Docbook-utils 0.6.14, Docbook-DSSSL 1.79, OpenJade 1.4devel1, opensp 1.5.2
@pbiering pbiering self-assigned this Dec 3, 2023
@pbiering pbiering added this to the 4.2.0 milestone Dec 6, 2023
@pbiering
Copy link
Owner

pbiering commented Dec 6, 2023

major extension to "generate.sh" by 384a2d1
Some notes:

  • xml export is required for (the somehow legacy) www.deepspace6.net CMS
  • reason for local copy of ldp.dsl: file is not availabe on Fedora or Enterprise Linux ("generate.sh" will now lookup for installed one before using local)

@paravoid : please test

@paravoid
Copy link
Author

paravoid commented Dec 6, 2023

That's great, thanks!

  1. generate.sh seems to have gained a Bashism (i.e. it fails when /bin/sh is set to e.g. dash). This fixes it:
--- a/doc/generate.sh
+++ b/doc/generate.sh
@@ -40,7 +40,7 @@ while getopts "h?L:" opt; do
     esac
 done
 
-shift $[ $OPTIND - 1 ]
+shift $((OPTIND - 1))
 
 if [ -z "$1" ]; then
        file_sgml="ipv6calc.sgml"
  1. The if [ ! -f $file_sgml ] block should be moved inside, or right before the validate_sgml call. Basically, I tried rm ipv6calc.{sgml,xml,html}; ./generate.sh -L ipv6calc.lyx, for good measure, which failed due to the SGML existence check, even though it's not actually required.

More minor issues:
a. validate_sgml and create_html_singlepage use set -x, but export_sgml does not. Is that intended?
b. There is a default of the SGML location (file_sgml="ipv6calc.sgml"), but not for the Lyx file, which needs to be passed in full. Is that intended?
c. At least in Debian sid, the generated HTML shows a tiny diff compared to the precompiled one:

--- a/doc/ipv6calc.html
+++ b/doc/ipv6calc.html
@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
 <HTML
 ><HEAD
 ><TITLE

@pbiering
Copy link
Owner

pbiering commented Dec 7, 2023

thank you for the comments, reworked now by
4a2785b and 141841a

The content of the HTML file is related to ldp.dsl, can you point me to the one used in Debian package?

@paravoid
Copy link
Author

paravoid commented Dec 7, 2023

The content of the HTML file is related to ldp.dsl, can you point me to the one used in Debian package?

https://packages.debian.org/sid/ldp-docbook-dsssl
->
https://packages.debian.org/sid/all/ldp-docbook-dsssl/download
->
http://ftp.de.debian.org/debian/pool/main/l/ldp-docbook-stylesheets/ldp-docbook-dsssl_0.0.20040321-3.1_all.deb

...and extract using dpkg -x ldp-docbook-dsssl_0.0.20040321-3.1_all.deb extract-dir, or, if you don't have dpkg, mkdir extract-dir && cd extract-dir && ar x ../ldp-docbook-dsssl_0.0.20040321-3.1_all.deb && tar -xzf data.tar.gz.

@pbiering
Copy link
Owner

pbiering commented Dec 7, 2023

Thank you for the ldp.dsl file source, the diff also explains why 4.0 instead of 4.01 was mentioned...regenerated now also:

3d973b0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@pbiering pbiering

Labels
enhancement
Projects
None yet
Milestone
4.2.0
Development

No branches or pull requests
2 participants
@paravoid @pbiering