Document the basic steps to generating the PDF with DDEV

I also use DDEV for this ... here's the setup that I'm using. It's got everything needed to generate the different versions of the guide. As well as run the tests to generate the automatic screenshots. And usually works. :P

https://github.com/eojthebrave/user_guide_tests_environment/tree/11.x

Thanks @eojthebrave, that was the last missing piece of the puzzle! I was experimenting, and getting close, and the "URW Palladio L" seemed to be the last piece ... Here's the text I was at, When I saw your comment:

I almost got it working in DDEV, but it looks like a font "URW Palladio L" can't be found ... I got the programs and fonts from the project README.txt and scripts/README.txt.

The packages xmlto, texlive-fonts-recommended and texlive-fonts-extra are necessary as well, it seems, to get the FreeSans and FreeMono fonts, or you get these errors:

mktextfm: `mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input FreeSans' failed to make FreeSans.tfm.
mktextfm: `mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input FreeMono' failed to make FreeMono.tfm.

See https://tex.stackexchange.com/questions/97123/problem-finding-metafonts-....

Possible method:

1. Create a DDEV project with this line at the bottom in .ddev/config.yaml (or add and restart DDEV), it takes a few minutes to complete:
   

   hooks:
     post-start:
      # Install additional packages.
       - exec: sudo apt-get update && sudo apt-get install -y asciidoc dblatex docbook fop texlive-lang-all texlive-xetex calibre fonts-noto-hinted unifont fonts-hosny-amiri fonts-babelstone-han fonts-takao xmlto texlive-fonts-recommended texlive-fonts-extra

2. Clone the User Guide project, enter the scripts folder and generate an English PDF

   $ cd user_guide/scripts
   $ ./mkall.sh 11.x en
   

Note: This alternative method of installing the packages ought to work in DDEV, but FreeSans and FreeMono are not available ...:

webimage_extra_packages: [asciidoc dblatex docbook fop texlive-lang-all texlive-xetex calibre fonts-noto-hinted unifont fonts-hosny-amiri fonts-babelstone-han fonts-takao xmlto texlive-fonts-recommended texlive-fonts-extra]

Result:

@drupal-web:/var/www/html/user_guide/scripts$ ./mkall.sh 11.x en
+ [[ 2 -lt 1 ]]
+ [[ 2 -gt 1 ]]
+ echo 'Building specified languages in parameters'
Building specified languages in parameters
+ langs=en
[...]
+ [[ -s dblatex-en.xsl ]]
+ dblatex --pdf -b xetex -T db2latex -p dblatex.xsl -o guide.pdf guide.docbook
Build the book set list...
Build the listings...
XSLT stylesheets DocBook - LaTeX 2e (0.3.12)
===================================================
Build guide.docbook.pdf
xelatex failed
guide.docbook.tex:25: Package fontspec Error: The font "URW Palladio L" cannot be found.
guide.docbook.tex:25: leading text: \setsansfont
guide.docbook.tex:25: Package fontspec Error: The font "URW Palladio L" cannot be found.
guide.docbook.tex:25: leading text: \setsansfont
[...]
guide.docbook.tex:13837: Font TU/URWPalladioL(0)/b/it/10="URW Palladio L" at 10.0pt not loadable: Metric (TFM) file or installed font not found.
guide.docbook.tex:13837: leading text: ...i.drupal.org}{\emph{api.drupal.org}} }]
Unexpected error occured
Error: xelatex compilation failed

About the "URW Palladio L" font, can't we replace it with a font included in one of the texlive-fonts packages to avoid jumping through hoops?

You can also edit the languages.txt file so that it only contains EN to build just the EN version of the PDF. Which can help eliminate some issues related to fonts and fop's handling of RTL languages.

And thanks for this tip, which I also figured out, not least to shorten processing time :)

Oh, and I just now realized that there's a .ddev folder, I'll try that and report back. Thanks!

I'm not opposed to switching to a different font. I didn't set this up initially so when I needed to figure out how to build it locally I was just looking for a work around and didn't want to break anything on the live site. We'll need to coordinate with the DA if we do to make sure the new font is installed on their infrastructure.

Also, long term, the plan is to move away from the current asciidoc tooling and to ... something else TBD. At some point something will be used for the new Drupal CMS User Guide, and we'll want to make sure this project uses the same build tools I think. It's very much in flux right now though ... https://www.drupal.org/project/user_guide/issues/3470837 📌 Decide on the future of the user guide Active . And mostly depends on the DA having time to implement something.

I didn't realize that the font in question is sort of "baked into" dblatex, which would of course make switching it out for another font a much more encompassing operation ... But your pragmatic solution with updating the parameter file to use "TeX Gyre Pagella" instead of "URW Palladio L" works well, and solves the problem elegantly.

I have created an MR which adds a DDEV Quickstart for the User Guide, so that new users can get started quickly. It installs the required Debian packages and fonts, substitutes the font mentioned, and adds the minimal commands required to generate a PDF version of the User Guide.

About the future ... yes, I am aware. I just hope that my opinion (that it should be kept "in house", under our control) and those who agree will be heard, when a decision is made.

PS. When I use the webimage_extra_packages method in DDEV, the fonts cannot be found (OpenFree, OpenSans, etc.):
webimage_extra_packages: [asciidoc, xmlto, docbook, fop, dblatex, texlive-lang-all, [...]

... my hunch is because some build processes are not done -- because it seems to run faster. If I instead use this method, everything works:

hooks:
  post-start:
    - exec: sudo apt-get update && [...]

Thanks for the DDEV configuration, and for testing it out. I'll merge this and I think we can call this fixed since you're able to generate a PDF to preview the guide, and it's in the README now too.

Sounds great, thanks for a fast review and commit, have a nice day :)

Automatically closed - issue fixed for 2 weeks with no activity.