Developers: translate the manual

[Davide Bucci]

Dear all,
translating the manual in a given language is something very useful for the
diffusion of FidoCadJ in a country in which this language is spoken.
The manual is a 50-some pages document written in LaTeX. You may understand
some LaTeX basics in order to work correctly. You will need only a very basic
text editor (avoid such things as Lyx). I used the classicthesis class, from
André Miede, which gives the nice classy style you see in the rendered
document.
In short, you will have to translate everything but the LaTeX commands. I
suggest you to find a short guide in order to understand how LaTeX works.
The best thing is to compare two versions of the manual in two different
languages. Here is the beginning of the file containing the source of the
manual in english language (manual_en.tex):

\documentclass[10pt,a4paper,twoside]{scrreprt}
\usepackage[english]{babel}

\usepackage{classicthesis-ldpkg} 
\usepackage[eulerchapternumbers,%drafting,%pdfspacing,%
            subfig,eulermath,parts]{classicthesis}
\pagestyle{headings}

\addtolength{\voffset}{9mm}   %>>> moves text field down
\usepackage[latin1]{inputenc}   % Encodage ISO-8859-1.
\usepackage{graphicx}
\graphicspath{{images/}} 
\newcommand{\keyevidence}[1]{\fbox{#1}}

\usepackage{pgf}

\usepackage{listings} 
\usepackage{makeidx}
\lstdefinelanguage{FIDOCAD} 
    {morekeywords={LI,PP,PV,TY,TE,MC,EV,EP,RP,RV,BE,SA,PA,PL,FCJ,FJC,%
        [FIDOCAD],[FIDOLIB]}, 
    sensitive=false, 
    morecomment=[s]{[}{]}, 
    morecomment=[s][\color{blue}]{\{}{\}}, 
    morecomment=[l][\color{violet}]{*},
    moredelim=[il][\color{violet}]{£},
}

\lstset{language=FIDOCAD,%
    basicstyle=\small\ttfamily}

% *******************************************************
% Hyperreferences
% *******************************************************
\hypersetup{%
    colorlinks=true, linktocpage=true, pdfstartpage=3, pdfstartview=FitV,%
    breaklinks=true, pdfpagemode=UseNone, pageanchor=true, pdfpagemode=UseOutlines,%
    plainpages=false, bookmarksnumbered, bookmarksopen=true, bookmarksopenlevel=1,%
    hypertexnames=true, pdfhighlight=/O,%hyperfootnotes=true,%nesting=true,%frenchlinks,%
    urlcolor=webbrown, linkcolor=RoyalBlue, citecolor=webgreen, %pagecolor=RoyalBlue,%
    % uncomment the following line if you want to have black links (e.g., for printing)
    %urlcolor=Black, linkcolor=Black, citecolor=Black, %pagecolor=Black,%
    pdftitle={FidoCadJ -- user manual},%
    pdfauthor={Davide Bucci},%
    pdfsubject={Comment utiliser FidoCadJ},%
    pdfkeywords={FidoCad, FidoCadJ, CAD, electronics schematics, printed circuit boards},%
    pdfcreator={pdfLaTeX},%
    pdfproducer={LaTeX with hyperref and classicthesis}%
}
\lstset{frame=single,%
    }

\newcommand{\micron}{\,\mu\mathrm{m}}

\title{\Huge\color{webbrown} FidoCadJ 0.23.4 \\ the user manual}


\author{Davide Bucci\\[3em]
\includegraphics[width=.7\textwidth]{icona_fidocadj_a}
}

 \makeindex


\begin{document}
\pagenumbering{roman}

\pdfbookmark[1]{Front}{Front}
\maketitle

\clearpage
\pdfbookmark[1]{Licence}{Licence}


\clearpage{} \pdfbookmark[1]{Licence}{Licence} This work is covered
by the Creative Commons Public License version 2.5 or more recent.
The entire text of this licence is available at the address\\
 \href{[url]http://creativecommons.org/licenses/by-nc-nd/3.0/[/url]}{[url]http://creativecommons.org/licenses/by-nc-nd/3.0/[/url]}.

You are free to reproduce, diffuse, communicate or expose in public,
represent, execute and play this work at the following conditions:
\begin{description}
\item [{Attribution}] {You must attribute the work in the manner specified
by the author or licensor (but not in any way that suggests that they
endorse you or your use of the work).} 
\item [{Noncommercial}] {You may not use this work for commercial purposes.} 
\item [{No Derivative Works}] {You may not alter, transform, or build
upon this work.} 
\end{description}
Any of the above conditions can be waived if you get permission from
the copyright holder (Davide Bucci). \vfill{}


All commercial names, logo, trademarks cited in this work are registered
by their owners.

\begingroup %\let\clearpage\relax
%\let\cleardoublepage\relax
%\let\cleardoublepage\relax



\chapter*{Abstract}

\pdfbookmark[1]{Abstract}{Abstract}

This document is the FidoCadJ official user manual. After a short
introduction of the history and the birth of this software, we will
describe the basic use of FidoCadJ. Our goal is to learn how to draw
very simple electronic schematics and their printed circuit boards.
The manual will end with a detailed description of the FidoCad (and
thus FidoCadJ) format, which has not yet been documented. \endgroup

And here is the same portion of the sources of the italian manual
(manual_it.tex):

\documentclass[10pt,a4paper,twoside]{scrreprt}
\usepackage[italian]{babel}

\usepackage{classicthesis-ldpkg} 
\usepackage[eulerchapternumbers,%drafting,%pdfspacing,%
            subfig,eulermath,parts]{classicthesis}
\pagestyle{headings}

\addtolength{\voffset}{9mm}   %>>> moves text field down
\usepackage[latin1]{inputenc}   % Encodage ISO-8859-1.
\usepackage{graphicx}
\graphicspath{{images/}} 
%\newcommand{\keyevidence}[1]{\fbox{#1}}
\newcommand{\keyevidence}[1]{\fbox{#1}}

\usepackage{pgf}

\usepackage{listings} 
\usepackage{makeidx}
\lstdefinelanguage{FIDOCAD} 
    {morekeywords={LI,PP,PV,TY,TE,MC,EV,EP,RP,RV,BE,SA,PA,PL,FCJ,FJC,%
        [FIDOCAD],[FIDOLIB]}, 
    sensitive=false, 
    morecomment=[s]{[}{]}, 
    morecomment=[s][\color{blue}]{\{}{\}}, 
    morecomment=[l][\color{violet}]{*},
    moredelim=[il][\color{violet}]{£},
} 
\lstdefinelanguage{plain} 
    {morekeywords={}, 
    sensitive=false, 
}

\lstset{language=FIDOCAD,%
    basicstyle=\small\ttfamily}

% *******************************************************
% Hyperreferences
% *******************************************************
\hypersetup{%
    colorlinks=true, linktocpage=true, pdfstartpage=3, pdfstartview=FitV,%
    breaklinks=true, pdfpagemode=UseNone, pageanchor=true, pdfpagemode=UseOutlines,%
    plainpages=false, bookmarksnumbered, bookmarksopen=true, bookmarksopenlevel=1,%
    hypertexnames=true, pdfhighlight=/O,%hyperfootnotes=true,%nesting=true,%frenchlinks,%
    urlcolor=webbrown, linkcolor=RoyalBlue, citecolor=webgreen, %pagecolor=RoyalBlue,%
    % uncomment the following line if you want to have black links (e.g., for printing)
    %urlcolor=Black, linkcolor=Black, citecolor=Black, %pagecolor=Black,%
    pdftitle={FidoCadJ -- manuale d'uso},%
    pdfauthor={Davide Bucci},%
    pdfsubject={Come utilizzare FidoCadJ},%
    pdfkeywords={FidoCad, FidoCadJ, CAD, schemi elettrici, circuiti stampati},%
    pdfcreator={pdfLaTeX},%
    pdfproducer={LaTeX with hyperref and classicthesis}%
}
\lstset{frame=single,%
    }

\newcommand{\micron}{\,\mu\mathrm{m}}

\title{\Huge\color{webbrown} FidoCadJ 0.23.4 \\ il manuale dell'utente}


\author{Davide Bucci\\[3em]
\includegraphics[width=.7\textwidth]{icona_fidocadj_a}
}

 \makeindex


\begin{document} 
\pagenumbering{roman}

\pdfbookmark[1]{Frontespizio}{Frontespizio}
\maketitle

\clearpage
\pdfbookmark[1]{Licenza}{Licenza}
Quest'opera è soggetta alla Creative Commons Public License versione 3.0 
o posteriore. L'enunciato integrale della Licenza in versione 3.0 è reperibile 
all'indirizzo internet:\\
\href{[url]http://creativecommons.org/licenses/by-nc-nd/3.0/deed.it[/url]}{[url]http://creativecommons.org/licenses/by-nc-nd/3.0/deed.it[/url]}.

 Si è liberi di riprodurre, distribuire, comunicare al pubblico, esporre, 
in pubblico, rappresentare, eseguire e recitare quest'opera alle seguenti 
condizioni: 
\begin{description}
\item[Attribuzione]{Bisogna attribuire la paternità dell'opera nei modi indicati 
dall'autore}
\item[Non commerciale]{Non si può usare quest'opera per fini commerciali. }
\item[Non opere derivate]{Non si può alterare o trasformare quest'opera, né
usarla per crearne un'altra. Ogni volta che si usa o si distribuisce quest'opera, lo si deve fare secondo i termini di questa licenza, che va comunicata con chiarezza. }
\end{description}
 In ogni caso si possono concordare con il titolare dei diritti d'autore (Davide Bucci) utilizzi di quest'opera non consentiti da questa licenza. 
\vfill
I nomi commerciali, i loghi, i trademark appartengono ai rispettivi proprietari.




\begingroup
%\let\clearpage\relax
%\let\cleardoublepage\relax
%\let\cleardoublepage\relax


\chapter*{Riassunto}

\pdfbookmark[1]{Riassunto}{Riassunto}
Questo documento è il manuale utente di FidoCadJ. Dopo una breve presentazione della storia del programma e della sua filosofia, verranno fornite le nozioni principali per disegnare un semplice schema elettrico ed un circuito stampato con FidoCadJ. La descrizione procederà poi con alcuni dettagli tecnici finora poco documentati, come la descrizione completa del formato testuale usato da FidoCad e di conseguenza da FidoCadJ\dots

\endgroup

You may notice at the very beginning the difference in the language specified
to the Babel packet:

\usepackage[english]{babel}




\usepackage[italian]{babel}

You may also see that almost all the code describing the setup of the document
is nearly the same.

Here is a reasonable way to do this work:
- rename manual_en.tex file to manual_xx.tex, where xx is the language code
- remember that a LaTeX command begins with a backslash. Do not translate LaTeX commands, translate instead all the text :-)
- something you may know is that the \index command is used to place something in the index of the document. You may want to translate what you see in curly braces if you want to obtain a useful index.
- do not translate the labels. They are in italian language, but they are coherent.
- you may provide a translated version of the figures or screenshots. Be very careful to respect exactly what you see in the original pictures. If in doubt, leave there the original pictures.

That's all, I hope!

Best regards and good work.

Darwin

[Davide Bucci]

ARGH! I see the code tag of the SF forum does not work very well. I do not
understand why almost all the code is struck through... Of
course, it should not be like that!

[Miles Qin]

hello darwinne,

I'm a chinese and I want to translate the manual into my native language.

At the beginning, I accorded to the method in the post above for translation,
but I have no a ability to config LaTeX to work on the Chinese file, sine I'm
a newborn for use of the LaTeX.

Then, I decided to divide translation job into two setps:

step 1, I'll translating the contents and saving to the MS Word file;
step 2, I'll learning about LaTeX and moving the contents to the LaTeX file.

now, I'm in step 1 and have some doubts about contents of the manual in
english, could you help me for my poor english ?

Best regards.

Miles

[Davide Bucci]

Dear Miles,
first of all, thanks again for all your efforts. I am sure that thanks to you
FidoCadJ can become a widely used program in China.

Of course, if you need any help for the translation, just ask and I will try
to answer to you.

BTW, since you already have write access to the source code repository, do not
be afraid of committing what you have done. I suggest putting your file in a
directory contained in trunk/manual. Something as follows:

trunk/manual/chinese

You might create this directory using your favorite tools, you put the file
containing your translation inside it and then you go to trunk/manual and you
do a "svn add chinese" command. Then, do not be afraid of committing regularly
your changes.

Best regards,

D.

[Miles Qin]

Dear darwinne,

Thank you very much for your encouragement, I'll do it.

and, I have the doubts : "The manual will end with a detailed description of
the FidoCad (and thus FidoCadJ) format, which has not yet been
documented." in page iv of fidocadj_manual_en.pdf.

the blod part "which has not yet been documented", I understanding is that
no descripton of the FidoCad format in this document, but there are presence
in chapter 3 ?

Best regards.

Miles

[Davide Bucci]

Hi Miles,
I understand what you mean. When I wrote this phrase (in summer 2008), people
knew FidoCAD for Windows, but not yet FidoCadJ. The original FidoCAD format
has never been described in detail before I wrote the FidoCadJ manual. Now, a
lot of people got acquainted with FidoCadJ but they never used FidoCAD, and
this is true especially outside Italy, since FidoCAD was only documented in
italian language.

Finally, I think you can drop this phrase in the translation, it might have
had a certain sense in 2008 in Italy: it is not the same in 2012 outside this
country.

If you have other questions, please ask.

Regards,

D.

P.S. I will have to update the manual in english soon to the new 0.24 version.
You will be able to see easily the places where I will be changing the text
using the SVN browser, but in any case, I need to add some stuff about the new
natural cubic spline primitive.

[Miles Qin]

Dear darwinne,

I heard about the earthquake in Italy and vary worried about you. are you all
right ?

Best regards.

Miles

[Davide Bucci]

Hi Miles,
this is very kind.
I live in France and so I have not been touched by the earthquake. However,
from what I read from newspaper, it appears that the situation is quite
critical in Emilia Romagna (a truly beautiful place).

Regards,

D.

[Miles Qin]

Dear darwinne,

oh, Hope that they are brave enough to face the disaster !

go on, I need your helps.

I have a doubt about "Thanks to Andrea D'Amore, for his advice concerning
FidoCadJ visual aspect on the Apple Macintosh, from the 0.21.1 version."
in page v of fidocadj_manual_en.pdf.

the blod phrase "from the 0.21.1 version" is the meaning of the advice
about FidoCadJ visual is achieved from the 0.21.1 version or Andrea D'Amore
was using FidoCadJ of 0.21.1 version and providing his advice ?

another doubt about "The success that FidoCadJ has had on
www.electroyou.it has stimulated some requests to implement a similar
system on other platforms, and in particular on www.electroyou.it,
another well known Italian electronics-dedicated website." in page 3 of
fidocadj_manual_en.pdf.

two websites is the same exactly, but they are two defferente websites in
contents.

Best regards.

Miles

[Davide Bucci]

Hi Miles,

the blod phrase "from the 0.21.1 version" is the meaning of the advice about
FidoCadJ visual is achieved from the 0.21.1 version or Andrea D'Amore was
using FidoCadJ of 0.21.1 version and providing his advice ?

Mainly that Andrea's suggestions were included in the 0.21.1 version.

"The success that FidoCadJ has had on www.electroyou.it has stimulated some
requests to implement a similar system on other platforms, and in particular
on www.electroyou.it, another well known Italian electronics-dedicated
website."

It's a typo! The second site should be www.grix.it

The english manual definitely needs to be reviewed, so thanks for your work.
Continuing this way we will improve it.

Regards,

Davide

[Miles Qin]

Dear darwinne,

I have a doubt about "If you need to align carefully the elements, you may
find useful to keep pressed Alt, while using the cursor keys." in page 5 of
fidocadj_manual_en.pdf.

I considered the meaning of the sentence above is the condition that I'm
adding or moving the element and needing to snap to grid when the button "Snap
to grid" is not pressed.

however, this is not the case after my practice, and a Pan icon is presence
when adding string in drawing with Alt pressed. there is a screenshot below.

( BTW, my OS is the windows xp sp3 and I post picture by url of my created
document in the project, is there another way to uploading the picture? ).

Best regards.

Miles

[Davide Bucci]

Dear Miles,
this section of the manual is probably not very clear. Here is what I am
meaning:
- in some cases, you might need to perform some adjustments to the position of elements without considering their alignment on the grid
- you first select the elements to be moved
- then you do not touch the mouse and on the keyboard just type Alt+cursor keys
- the selected elements will be moving 1 logical unit in the direction of the key you typed

If you see the pan icon appearing, I think you are pressing Alt and then
clicking on the drawing with the mouse.

For what it concerns the images on the SF forum, I am not aware of any simple
way to store them on the SF website. You might find some external host. Once
upon a time I used Imageshack for similar needs, but it seems that it needs a
registration to be used now.

Regards,

D.

[Davide Bucci]

Just forgot a detail: Miles, you might consider upgrading FidoCadJ to the
version 0.24 I put online a few days ago. It will be much more stable than the
beta you are using (a greek letter means that it is a preliminary version).

Regards,

D.

[Davide Bucci]

Hi Miles,
I just had a look at your commit and I see that you are in a pretty advanced
stage of the translation.
I would like just to warn you that I still have some corrections and slight
changes to be done to the English manual. Concerning the LaTeX point of view,
I decided to not using classicthesis style anymore, since it appears not to be
very compatible with the LaTeX configuration I like to use. I went back to a
less distinctive style, like the one of the new Italian manual.

Regards,

Davide

[Davide Bucci]

Dear Miles,
I just upgraded the English manual to version 0.24, basically providing the
missing information about the spline curves. If you want to see what I
changed, you might use the SF svn browser:

http://fidocadj.svn.sourceforge.net/viewvc/fidocadj/trunk/manual/manual_en.te
x?view=log

Regards,

D.

[Miles Qin]

Dear darwinne,

I already compared and updated the manual and now I have been doing
translating by new version.

I noticed that "View/Option" is moved to "File/Option" in Version 0.24,
however not modified in file "FidoCadJ 0.24 user manual".

Best regards.

Miles

[Davide Bucci]

Dear Miles,
you are right, I will update the manual with your remark.
BTW, have you noticed that a version 0.24.1 is in preparation, with some
modifications done to the manuals (sorry for that, but they are details,
albeit important ones).
I think what it would be nice is to align your Chinese translation to 0.24.1,
such that when this version will come out, we will have the English, Chinese
and Italian manuals synchronized and updated. I should update also the French
manual a day or another...

BTW, have you tried using LaTeX, or you plan leaving the manual in OpenOffice?
You can choose the second possibility if you think it will be easier for you.

Regards,

Davide

[Miles Qin]

Dear darwinne,

Thank you for your remind, I'll track the updating.
but I don't think my translation can be released currently for two reasons
following.

1, My translation seems to have been completed, but that is random. In order
to avoid misleading readers, I need to seriously check it again. now I'm
checking it.

2, I want to transfer my translation to LaTeX for consistent with the way of
writting manual in this project.

The translation will be released, after two tasks above are completed.

BTW, I'm a little busy recently, Please forgive me for the slow working.

Best regards.

Miles

[Davide Bucci]

Dear Miles,
do not worry if you have the impression of working slowly. Doing a nice
translation of a 60 pages document is not an easy task and I really appreciate
your attentive analysis of the english manual.
If you need any help concerning LaTeX, just ask and I will try to answer.

Best regards,

D.

[Miles Qin]

Dear darwinne,

I found that toolbars and dialogs of application can displaying well in
chinese, but drawing area can not. there is a screenshot blow.

Best regards,

Miles

[Davide Bucci]

Hi Miles,
the text primitive of FidoCadJ is fully supporting the UTF-8.
What you see there is probably due to the fact that the font you selected for
the text does not contains the glyphs you need.
FidoCadJ relies on the fonts available on the operating system. Try to change
the font used for this text line, with one containing the characters you wants
to display.

Regards,

D.

[Miles Qin]

hello Miles,

thank you for your Explanation, that's all right !

Regards,

miles

[Miles Qin]

Hello darwinne,

Is there lack a item (should be curve) in chapter 3.3 of the latest manual.

BTW.

By Reading with the contents before chapter 3, the drawing tools on command
bar call basic elements (the primitives), and the elements in libraries call
macro. so I understanded the drawing elements may well divided into two
categories: the primitives and the macros. Further on a macro was drawed by
the primitives and other macros.

However in chapter 3.3, there mixing with the primitives and the macros, and
collectively referred to as drawing primitives.

Could you help me for my understanding ?

Regards,

miles

[Davide Bucci]

Dear Miles,
many thanks for your remarks.
I tried to take them into account. In particular, I think that in some parts
of the chapter 3.3 it is better to use the term "graphic elements" instead of
"primitives". It should be less prone to lead the reader into a confusion and
it allows to make a difference between macros and primitives.
I tried to correct what I could. If there is something which is not clear or
not very precise, I will implement other corrections.

Best regards,

D.

[Miles Qin]

Dear darwinne,

I can not understand the sentence "FidoCadJ provides in practice an electronic
version of the good old R41 transfers." in the 1st paragraph of chapter 2.5,
in particular the "R41".

Would you give an explaination. thank you very much !

Best regards.

Miles