# Building documentation as PDF



## anbj (Dec 11, 2020)

Hi,

I'm trying to follow this guide, https://freebsdfoundation.org/contributing-freebsd-documentation/, to build the documentation in PDF.

According to the guide, I should be able to do a `%  make -V KNOWN_FORMATS`, where _KNOWN_FORMATS_ can be html, html-split or pdf.

If I try to build as pdf, all I'm getting in a blank newline, and nothing else.


```
$ make -V pdf
<blank line>
$
```

The same applies to `make -V html` and `make -V html-split`. Issuing just `make`, works and generates html.

Any tips?


----------



## SirDice (Dec 11, 2020)

anbj said:


> I should be able to do a `% make -V KNOWN_FORMATS`, where _KNOWN_FORMATS_ can be html, html-split or pdf.


No, you misread that. Issuing `make -V KNOWN_FORMATS` will show you which formats are available (for now it should return html, html-split and pdf). You set the FORMATS variable to one or more formats you want. In your case that would be `make -DFORMATS=pdf` to generate the documentation in PDF. 

The `-V` option shows what the value of a variable is, in this case KNOWN_FORMATS. There are no variables named html or pdf, that's why they just return an empty line.

```
-V variable
             Print the value of variable.  Do not build any targets.  Multiple
             instances of this option may be specified; the variables will be
             printed one per line, with a blank line for each null or
             undefined variable.  The value printed is extracted from the
             global context after all makefiles have been read.  By default,
             the raw variable contents (which may include additional
             unexpanded variable references) are shown.  If variable contains
             a `$' then the value will be recursively expanded to its complete
             resultant text before printing.  The expanded value will also be
             printed if .MAKE.EXPAND_VARIABLES is set to true and the -dV
             option has not been used to override it.  Note that loop-local
             and target-local variables, as well as values taken temporarily
             by global variables during makefile processing, are not
             accessible via this option.  The -dv debug mode can be used to
             see these at the cost of generating substantial extraneous
             output.
```
See make(1).


----------



## a6h (Dec 11, 2020)

I think you should study or at least skim through "_FreeBSD Documentation Project Primer for New Contributors_" Book
I. Online version: https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/
II. Offline versions: https://download.freebsd.org/ftp/doc/en/books/fdp-primer/


----------



## anbj (Dec 12, 2020)

Oh, boy. That's embarrassing. Thanks for helping me out.

So, _$ make -V KNOWN_FORMATS_ gives me _html html.tar html-split [..] pdf._

Alright, make me the PDF-version:

_make -DFORMATS=pdf_

All I get is the html-pages!

PS! I have installed the required tools (https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html#tools-required)


----------



## T-Daemon (Dec 12, 2020)

anbj said:


> Alright, make me the PDF-version:
> 
> _make -DFORMATS=pdf_
> 
> ...


Have you installed textproc/fop:

1.1. Quick Start

```
2.0 Optional: to generate PDF documentation, install the textproc/fop package as it is not installed by default
by textproc/docproj.

# pkg install fop
```


----------



## anbj (Dec 12, 2020)

Yes, fop is installed.


----------



## anbj (Feb 10, 2021)

No, I never managed to create the PDFs.

Haven't tried again after the doc was converted to Asciidoctor.


----------

