linuxcncAllWasm/docs/README.adoc

: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., a new document belonging to the Master
Documentation requires an entry 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/`.

Every translated HTML page is emitted regardless of completeness; the
topbar language-switcher post-process greys out per-page entries whose
`.po` coverage falls below `POKEEP` percent (default 80). Override at
build time: `make POKEEP=30 docs` to surface in-progress translations,
`make POKEEP=0 docs` to keep every entry clickable. See
`docs/src/code/contributing-to-linuxcnc.adoc` for details.

== 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. It is not clear 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.

At the moment, build rules are created for languages with more than 2
percent translated
link:https://hosted.weblate.org/projects/linuxcnc/linuxcnc-docs/[according
to Weblate] or which have been updated the last 12 months according to
the PO-Revision-Date field in docs/po/*.po.  Documentation packages for
Debian are build for languages with more than 50 percent translation.
This ensure translators and proof readers can see the result of their
effort on https://linuxcnc.org/docs/devel/html/, while we limit the
time spent building translations to those that are actively worked on
or at least have a very the bare minimum translated.

Add the new language code to the [po4a_langs] section of 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: