:lang: en
:toc:
= README for Document Writers
== Adding files
The src/Submakefile, src/docs.xml, docs/po4a.cfg and src/index.tmpl
files must be updated to add a new document file.
The relevant pdf.adoc must be updated to include the new document in the
pdf documentation. e.g. if a new document belongs in the Master
Documentation then an entry is required in src/Master_Documentation.adoc.
docs.xml is used to create the "previous" and "next" buttons at the top
of each individual HTML document. It should generally match the order of
the index.tmpl.
po4a.cfg is used to map source files to translated documentation when
generating translated files using the files in docs/po/.
== Notes on LinuxCNC documentation
The main LinuxCNC makefile can optionally build the documentation and
other files in this directory tree. Use "--enable-build-documentation"
when invoking src/configure, and run "make" from src.
== Notes about drawings
Many of the documents include drawings. Most of them originally
created using the non-free Windows app EasyCAD and then exported to .eps
files and included in the the docs. The original 'source' files
(EasyCad .FC7 format) were not usable on a free system. To fix this
problem, all of the source files have been converted to .dxf files,
and added to Git. The .dxf files can be edited with multiple CAD packages,
and serve as the 'source' files for future changes to the drawings.
They can be converted from .dxf to postscript (not .eps) using QCAD,
which is available for many systems, see link:https://repology.org/project/qcad/[here].
Unfortunately, EasyCAD (and AutoCAD) support a number of entities
that QCAD does not import properly. Including some that were used
in the LinuxCNC drawings: filled circles, filled arrowheads, non-zero
width lines, and dashed lines. Qcad renders filled circles as
hollow, it renders all lines the same width, and it renders dashed
lines as solid, unless you tell it to do otherwise. All of these
things make the drawings less attractive, but are somewhat
acceptable. However, Qcad doesn't import filled arrowheads at all,
which seriously hurts the drawings. So EasyCad was used to convert
the arrowheads to hollow before exporting them. Hollow arrowheads
don't look as nice as solid ones, but at least they are visible.
Once exported, the arrowheads lose their relationship with the line they
are on, and need to be moved and/or rotated manually if the line is
moved. I believe that even if they were imported back into EasyCad, the
line/arrow connection would remain broken. New lines with arrowheads can
be created in Qcad with the 'leader' dimension tool.
Because the original EPS files with filled lines and circles, wide lines,
and dashed lines look so much nicer, they will remain in Git and should
probably be used for the documents, however if they become inaccurate
because of changes in the software, we will have to edit the DXF files,
generate PostScript, and use the less pretty, but factually correct
images.
Since QCAD itself is a GUI application, the DXF to PostScript conversion
involves going clicky clicky, and can't be automated and made part of the
makefile. Also, not everyone will have QCAD installed on their system.
Therefore, both the DXF files and the resulting postscript
files are stored in Git, and the normal documentation build process only
uses the PostScript files. If/when the DXF files are edited, they have
to be converted to PostScript manually as follows:
- Start QCAD
- File → Open → choose DXF file (the drawing appears in window)
- Edit → Current Drawing Preferences → Paper +
Set:
* Paper size to "Letter",
* Orientation to "Landscape" or Portrait", depending on the aspect
ratio of the drawing.
- File → Print Preview +
Click the "Fit to page" button on the toolbar (last button on the
right - at least on version 2.0.4.0 of QCAD).
- File → Print
* Select "Print to file".
* Set the path to point to the same directory as the source .dxf file.
* Set the name to be the same as the source file, but .ps instead
of .dxf.
* Click "OK".
The makers of QCAD also have a GPL'ed format converter called vec2web,
which can do dxf to postscript conversion from the command-line. It
is not available as a pre-compiled package, but available in source
form from https://github.com/Seablade/vec2web.
vec2web depends on Qt 3 development packages to compile, so it should
not be a dependency for building the LinuxCNC docs. But if configure can
detect it, it would be nice to automate conversion from DXF to PS for
systems where vec2web is installed.
To build vec2web, apt-get install qt3-dev-tools.
The vec2web tarball contains a build script, but before you run it you
must set $QTDIR to point at your Qt 3 installation — in my case it was:
```
export QTDIR=/usr/share/qt3
```
Then run the build script:
```
./build_vec2web.sh
```
There is no install step, the executable gets dumped into the build
directory.
There is also no man page, but running it with no args prints the
following usage instructions:
```
Usage: vec2web