204 lines
8.4 KiB
Text
204 lines
8.4 KiB
Text
: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 <input file> <output file> [options]
|
||
Where options are:
|
||
-x # maximum x size for the output bitmap in pixel
|
||
-y # maximum y size for the output bitmap in pixel
|
||
-b black/white instead of using colors
|
||
-o [l|p] orientation for PS output (landscape or portrait)
|
||
-s .. page size for PS output (A4, A5)
|
||
|
||
e.g. vec2web drawing.dxf drawing.png
|
||
converts drawing.dxf to a portable network graphic
|
||
```
|
||
|
||
Initial attempts to use vec2web resulted in the graphical parts of the
|
||
drawing being converted, but all text was lost. I don't know if vec2web
|
||
is worth spending much more time on, however, it _is_ GPLv2, and it
|
||
includes a library for reading DXF files, which might be worthwhile to
|
||
the LinuxCNC community.
|
||
|
||
=== Drawings from QCAD
|
||
|
||
- Save as .dxf to the same directory as the image.
|
||
- Set line thickness to 0.50 mm.
|
||
- Export the image as 480 x 480 Resolution Auto .png.
|
||
|
||
== Provide translated documentation
|
||
|
||
The complete set of documents are translated using gettext PO files
|
||
using the https://po4a.alioth.debian.org/[po4a]po4a system. If you
|
||
want to contribute a translation, please use the
|
||
link:https://hosted.weblate.org/projects/linuxcnc/[web based
|
||
translation editor Weblate]. Registered Weblate users can translate
|
||
directly, while non-registered users can propose translations for
|
||
others to review. Translations are done paragraph by paragraph. If
|
||
there is no existing translation of the documentation to your
|
||
language, you can add it in the Weblate interface.
|
||
|
||
With po4a, the English text is the master document, and each paragraph
|
||
is translated using gettext, just like the strings in our software.
|
||
Some documentation of po4a is available in the
|
||
https://po4a.alioth.debian.org/man/man7/po4a.7.php[po4a(7)] manpage.
|
||
As the po4a support for asciidoc has been rapidly improving since
|
||
LinuxCNC started using it, based on bug reports from the LinuxCNC
|
||
community, a very recent version of po4a is needed. At the moment, at
|
||
least version 0.67 is needed, available in Debian Bookworm.
|
||
|
||
=== When the master document (english) changes
|
||
|
||
When the master document (english) file has changed, the POT file with
|
||
the set of translatable strings need to be updated, and the updates
|
||
need to be propagated into the PO files for each translation. This
|
||
can be done using the build system:
|
||
|
||
```
|
||
make -C src translateddocs
|
||
```
|
||
|
||
Once this is completed, the files in docs/po/ will be updated, and
|
||
should be committed into git and pulled into Weblate.
|
||
|
||
=== How to add a new translation language
|
||
|
||
Once a new PO files for a fresh translation is added via Weblate, and
|
||
the translation level raise to a sensible level (for example not 0%),
|
||
build rules need to be added to use the generated translations to
|
||
build HTML and PDF editions of the translation.
|
||
|
||
Add the new language code to the proper place in docs/po4a.cfg.
|
||
Update build rules for the new language in `docs/src/Submakefile`.
|
||
|
||
Edit debian/control.in to add the new linuxcnc-doc-$NEWLANG package.
|
||
Add the new doc package to the "or" list of the "Recommends" line of the
|
||
linuxcnc main package.
|
||
|
||
Add the new language to the list in the DOCS_PACKAGES variable in
|
||
debian/configure.
|
||
|
||
If there is a texlive-lang-$NEWLANGUAGE package for your new language,
|
||
add it to the DOC_DEPENDS variable in debian/configure.
|
||
|
||
Add the appropriate `linuxcnc-doc-$NEWLANG.*` files for the new package,
|
||
probably by copying and editing `debian/linuxcnc-doc-en.*`.
|
||
|
||
Test build the packages and verify!
|
||
|
||
// vim: set syntax=asciidoc:
|