141 lines
6.5 KiB
Text
141 lines
6.5 KiB
Text
README for Document Writers
|
|
|
|
Adding files:
|
|
-------------
|
|
The submakefile, docs.xml and index.tmpl must be updated to add a file to the documents.
|
|
|
|
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
|
|
|
|
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 [](https://repology.org/project/qcad/versions)).
|
|
|
|
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 corrrect
|
|
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→CurrentDrawingPreferences→Paper
|
|
Set paper size to "Letter", set orientation to "Landscape" or "Portrait"
|
|
depending on the aspect ratio of the drawing.
|
|
File→PrintPreview
|
|
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 Linux CNC
|
|
community.
|
|
|
|
Drawings from QCAD
|
|
-------------------
|
|
Save as .dxf to the same directory as the image
|
|
Set line thickness to 0.50mm
|
|
Export the image as 480 x 480 Resolution Auto .png
|
|
|
|
|
|
How to add a new translation language
|
|
-------------------------------------
|
|
|
|
Add the asciidoc source files containing your new translation.
|
|
Usually that means copying the language files from one of the existing
|
|
languages, probably English since that's usually the most up-to-date.
|
|
|
|
Add the new files to the proper place in docs/src/Submakefile, to ensure
|
|
they get built.
|
|
|
|
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/linuxcnc-sim package.
|
|
|
|
Add the new language to the DOCS_PACKAGES variable in debian/configure.
|
|
If there is a texlive-lang-$NEWLANGUAGE package for your new language,
|
|
add it to all the appropriate EXTRA_BUILD lines in debian/configure.
|
|
|
|
Add the 'linuxcnc-doc-$NEWLANG.files.in' file for the new package, probably
|
|
by copying and editing "debian/linuxcnc-doc-en.files.in".
|
|
|
|
Test build the packages and verify!
|