Merge pull request #59 from neilt/refactoring-2023-11

Refactoring 2023 11

README.md

@@ -2,15 +2,15 @@
 
 For LedgerSMB Small and Medium business accounting and ERP
 
-# DESCRIPTION
+## DESCRIPTION
 
 The LedgerSMB Book is the documentation for the open source [LedgerSMB](https://ledgersmb.org) small and medium business accounting and ERP system.
 
 The source for the LedgerSMB accounting system can be found on [github](https://github.com/ledgersmb/LedgerSMB).
 
 The source for the LedgerSMB Book can be found on [github](https://github.com/ehuelsmann/ledgersmb-book).
 
-# Build Requirements
+## Build Requirements
 
 The book should build with any recent LaTeX installation. The book is expected to produce both HTML and PDF and is currently tested with:
 
@@ -26,7 +26,7 @@ The Book also builds in PDF format without using the `local-build.sh` script usi
 
 The first time the book is built in a clean repository using TeXstudio or TeXShop the glossary or index build may error out or not be included into the PDF. This is normally fixed by making sure that TeXstudio or TeXShop are using `latexmk` instead of `pdflatex` for the build command.
 
-# Development Requirements
+## Development Requirements
 
 Since the build process uses LaTeXML the only packages that can be in the LaTeX source are those compatible with LaTeXML.  The acceptable package list can be found at [LaTeXML Bindings](https://math.nist.gov/~BMiller/LaTeXML/manual/included.bindings/).
 
@@ -50,7 +50,7 @@ Used as follows:
 Additional technical documentation which is useful when writing documentation can be found at:
 [https://docs.ledgersmb.org](https://docs.ledgersmb.org)
 
-# Scripts Directory
+## Scripts Directory
 
 The directory `scripts` contains Perl scripts used to manually retrieve information from various sources for inclusion in the book.
 

scripts/development-notes.md

@@ -0,0 +1,121 @@
+# LedgerSMB Book Development Notes
+
+Collected notes about development in this repository.
+
+## Local Test Environment
+
+Using `ubuntu-20.04.6-live-server-amd64.iso` as the base run the following:
+
+```bash
+#!/bin/bash
+set -e
+set -x
+
+# Setup Ubuntu to make LSMB Book 
+sudo apt update
+sudo apt -y upgrade
+
+# These installs are from the book github action, which should always be consulted for changes.
+# https://github.com/ehuelsmann/ledgersmb-book/blob/master/.github/workflows/typeset.yml
+sudo apt-get install -y gcc make cpanminus libxslt1-dev libxml-libxml-perl 
+sudo apt-get install -y texlive-latex-extra texlive-fonts-recommended libxml-perl latexml
+
+# For local-build.sh
+sudo apt-get install -y latexmk
+
+# For `gather-db-info.pl`
+
+# For `get-screen-shots.pl`
+
+git clone https://github.com/neilt/ledgersmb-book.git
+
+sudo shutdown -r now
+```
+
+## Experimenting with alternative converters to HTML
+
+### LaTeXML
+
+LaTeXML version 0.8.7 has problems with TeX Live 2023. The conversion hangs. The problem is known at LaTeXML upstream, but as of 19 Nov 2023 no solution has been released.
+
+[Issue 2109](https://github.com/brucemiller/LaTeXML/pull/2109)
+
+[Issue 2151](https://github.com/brucemiller/LaTeXML/pull/2151)
+
+[Issue 2064](https://github.com/brucemiller/LaTeXML/issues/2064)
+
+[Issue 2124](https://github.com/brucemiller/LaTeXML/issues/2124)
+
+Fixes have been merged, waiting on release.
+
+### hevea (19 Nove 2023)
+
+[Github Source](https://github.com/maranget/hevea)
+
+[Home Page](https://hevea.inria.fr)
+
+```bash
+hevea ledgersmb-book.tex
+
+./ledgersmb-book.tex:38: Warning: Command not found: \setlist
+./ledgersmb-book.tex:66: Warning: Command not found: \makeglossaries
+./ledgersmb-book.tex:68: Warning: Command not found: \ifdefined
+./ledgersmb-book.tex:68: Warning: Command not found: \LaTeXML
+./acronyms.tex:5: Warning: Command not found: \newacronym
+./acronyms.tex:6: Warning: Command not found: \newacronym
+./acronyms.tex:7: Warning: Command not found: \newacronym
+./acronyms.tex:8: Warning: Command not found: \newacronym
+./acronyms.tex:9: Warning: Command not found: \newacronym
+./acronyms.tex:10: Warning: Command not found: \newacronym
+./acronyms.tex:11: Warning: Command not found: \newacronym
+./acronyms.tex:12: Warning: Command not found: \newacronym
+./acronyms.tex:13: Warning: Command not found: \newacronym
+./acronyms.tex:14: Warning: Command not found: \newacronym
+./acronyms.tex:15: Warning: Command not found: \newacronym
+./acronyms.tex:16: Warning: Command not found: \newacronym
+./acronyms.tex:17: Warning: Command not found: \newacronym
+./acronyms.tex:18: Warning: Command not found: \newacronym
+./acronyms.tex:19: Warning: Command not found: \newacronym
+./acronyms.tex:20: Warning: Command not found: \newacronym
+./acronyms.tex:21: Warning: Command not found: \newacronym
+./acronyms.tex:22: Warning: Command not found: \newacronym
+./acronyms.tex:23: Warning: Command not found: \newacronym
+./acronyms.tex:24: Warning: Command not found: \newacronym
+./ledgersmb-book.tex:97: Giving up command: \include
+./acronyms.tex:24: Error while reading LaTeX:
+	Non-ascii '?' in input, consider using package inputenc
+Adios
+
+```
+
+### LaTeX2HTML (19 Nove 2023)
+
+[Github Source](https://github.com/latex2html/latex2html)
+
+[Home Page CTAN](https://www.ctan.org/pkg/latex2html)
+
+[Home Page](https://www.latex2html.org)
+
+```bash
+latex2html -help
+perldoc latex2html
+
+LaTeX2HTML ledgersmb-book.tex
+
+*********** WARNINGS ***********  
+No implementation found for style `lmodern'
+No implementation found for style `url'
+No implementation found for style `palatino'
+No implementation found for style `enumitem'
+No implementation found for style `makecell'
+No implementation found for style `glossaries'
+No implementation found for style `metalogo'
+
+Substitution of arg to newlabelxx delayed.
+
+? brace missing for \oldnewlabel
+
+Unknown commands: acrshort footref printglossary setlist makecell else makeglossaries protected_at_file_at_percent LaTeXML ifdefined protected cleardoublepage fi ifpdf bullet XeLaTeX newacronym glspl newglossaryentry gls hypersetup 
+Done.
+
+```

local-build.sh → scripts/local-build.sh

@@ -1,18 +1,27 @@
-#!/bin/sh
+#!/bin/bash
 
 # For local build and testing
 set -e 
 
 base_path=.
 img_path=$base_path/images
-dest_path=$base_path/local-build
+dest_path=$base_path/scripts/local-build
 tmp_path=/tmp
 
+# Backup to the root directory for processing
+cd ..
+
+# Older versions of this script had this directory at the root,
+# which is no longer used.
+rm -rfv local-build
+
+# Make sure the destination exists
 mkdir -p $dest_path
-cd $base_path
 
 if [[ $1 = '--use-pdf-latex' ]]; then
 
+    # Builds everything needed or not
+
     # Set the stage for building the glossaries
     pdflatex -file-line-error ledgersmb-book.tex
     # Build the glossaries
@@ -22,25 +31,22 @@ if [[ $1 = '--use-pdf-latex' ]]; then
 
 elif [[ $1 = '--use-latex-mk' ]]; then
 
-    # Make PDF
-    # Not able to get latexmk to process glossaries correctly right now.
+    # Only builds files that have changed
+    #    -diagnostics \
+
     latexmk -dvi- \
-        -gg \
         -interaction=nonstopmode \
         -pdf \
         -silent \
-        -pdflatex \
-        # -aux-directory=${tmp_path} \
-        # -output-directory=${base_path}
         ledgersmb-book.tex
 
 else
 
-    # Check for help or no args to provide help.
+    # Show help when one of --use-latex-mk or --use-pdf-latex is not provided.
     echo "Required options to $0 are one of:"
     echo "  --help"
-    echo "  --use-pdf-latex"
-    echo "  --use-latex-mk # FIXME: Not working right now."
+    echo "  --use-pdf-latex (not recommended anymore)"
+    echo "  --use-latex-mk"
     if [[ $1 != '--help' ]]; then
         echo "One arg must be specified."
         exit 1
@@ -49,9 +55,12 @@ else
 
 fi
 
+# move the pdf so it does not get cleaned up
+mv ledgersmb-book.pdf ${dest_path}
+
 echo 'Make XML'
 latexml --inputencoding=utf-8 \
-        --path=$img_path/ \
+        --path=${base_path}/$img_path/ \
         --destination=book.xml \
         --verbose \
         $base_path/ledgersmb-book.tex
@@ -89,16 +98,10 @@ for i in full-book split-book ; do
   mv $tmp_path/$i $dest_path
 done
 
-# move the pdf so it does not get cleaned up
-mv ledgersmb-book.pdf ${dest_path}
-
-
 # echo 'Clean up the latex files'
-# This means everything will be rebuild from scratch next time.
-# Probably a better way to do this like moving the aux files to /tmp.
+# This means everything will be rebuilt from scratch next time.
 # latexmk -C
 
-
 echo "The full book can be found at: $dest_path/full-book/index.html"
 echo "The split book can be found at: $dest_path/split-book/index.html"
 echo "The pdf can be found at: $dest_path/ledgersmb-book.pdf"