README file for FidoCadJ

Copyright 2007-2014

by Davide Bucci

----------------
1 - Introduction
----------------

FidoCadJ is a very easy to use editor, with a vast library of electrical 
symbols and footprints (through hole and SMD). Its drawings can be exported
in several graphic formats (PDF, EPS, PGF for LaTeX, SVG, PNG, JPG). Even if
it is very simple and somewhat limited, FidoCadJ can be very useful as a basic
schematic capture and electronic design automation (EDA) software. FidoCadJ 
is inspired from FidoCAD (without "J"), which was a vector graphic editor 
useful for electrical schematics and printed circuit boards. 
FidoCAD used a file format containing UTF-8 text, very compact and 
perfect for copy and pasting from/into newsgroups and forum messages. 
This determined its success among the italian Usenet community and forums, 
from late '90s, as it is quite versatile for simple mechanical drawings as 
well. FidoCadJ is the modern successor of FidoCAD.

No netlist concept lies behind the drawings, so there is all the graphical
flexibility that a vector drawing software can offer (but no simulation).

FidoCadJ is internationalized and its manual is available in English, French, 
Italian and Chinese translations. The user interface has been translated 
into English, French, Italian, Spanish, German, Chinese, Dutch, Japanese, 
Czech.

Here are a few useful sites about FidoCadJ:

    http://tinyurl.com/yavewp2
    http://sourceforge.net/projects/fidocadj/

If you own a PC running Linux or Windows (or any system supporting Java), you
may download from the SourceForge repository the file fidocadj.jar. If Java
is correctly installed on your machine, you may just double click on it to 
run FidoCadJ. If you are a command line wizard, you may go to the directory
where the file fidocadj.jar has been saved and type:

    java -jar fidocadj.jar

If you use Windows, you might find useful using the classical installer
contained in the FidoCadJ_Windows.exe file. If you run it, it will install
FidoCadJ on your system and you can launch it via the Start menu.
    
If you own an Apple Macintosh with MacOSX, you may download the FidoCadJ.app
bundle and treat it just like any other native application. Since Apple does
not seem to be very much prone to support Java, if you experience some 
problems running FidoCadJ, please check you do have a Java runtime 
correctly installed on your Mac. This is particularly true if you are using
the MacOSX Lion/Mountain Lion/Mavericks operating system. Normally, you will 
have to download the Java runtime in a few clicks. We tried our best, but
the situation in 2007 was different from the actual one and Apple used to
welcome Java developers back then...

Remember that if there is a Greek letter after the version number of FidoCadJ,
this means that you are using a preliminary version of this program. 
Basically, you are warned: those versions may be unstable!

----------------------------------------------
2 - Files contained in the source distribution
----------------------------------------------

In the following table you find a description of the trunk directory of 
FidoCadJ source files. You may download the complete source repository by
using svn from the SourceForge repository. Check out the SF documentation
for doing this: https://sourceforge.net/p/fidocadj/code/HEAD/tree/6

  File                        Comments
  ----------------------------------------------------------------------------
  README                      This file
  bin/                 DIR    Contains all the compiled classes and resources         
  busy being born/     DIR    Contains screenshots of old versions of FidoCadJ
  clean                       erases all the compiled classes
  cleanall                    does a clean, erases fidocadj.jar, Javadocs
  compile                     compile FidoCadJ
  count                       does a wc (word count!) on all Java source files                    
  createdoc                   runs Javadoc on all source files
  createjar                   prepares fidocadj.jar
  doc                         contains all Javadoc produced HTML files
  gpl-3.0.txt                 the GNU public licence v. 3
  icons/               DIR    contains all icons (made with Gimp)
  jar/                 DIR    contains fidocadj.jar as well as Quaqua
  OSes/                DIR    contains files specific for some OS
  manual/              DIR    all the LaTeX manuals sources
  profile                     launches a profiler (jip)
  rebuild                     does a clean and then runs FidoCadJ
  run                         run FidoCadJ
  src/                 DIR    contains all the Java source files
  exclude_from_svn            excludes all binary generated files from svn
  sign.sh                     creates the signature for the applet
  test/                DIR    automatic tests for FidoCadJ
  winbuild.bat                build and run script for Windows (see par. 3.3)

-----------------------------------------------------
3 - Instructions about compiling and running FidoCadJ
-----------------------------------------------------

Ok, you just checkout from SourceForge SVN the FidoCadJ source files. Good :-)
FidoCadJ is a pure Java project, and for many reasons I prefer using a good
text editor as well as a few command line scripts, in order to compile and run 
the code on which I am working.
You will thus find in the trunk directory (see section 2 of this 
file) several scripts which will be useful for you, especially if you are
working in an Unix-like environment.
If you prefer using some kind of IDE such as Eclipse, you may try, but I
do not provide assistance about it and I will always refer to the scripts
I wrote. And no, I will not change my habits, sorry :-)

3.1 Compile and run the sources on a MacOSX operating system (>=1.4.11) 
-----------------------------------------------------------------------

If you are using MacOSX, just open up a terminal window, go into the 
fidocadj/trunk directory and type:

    ./rebuild

FidoCadJ should be automatically compiled and launched. You can use the 
following script to create a jar archive in the jar/ directory:

    ./createjar

3.2 Compile and run the sources on an Unix system
-------------------------------------------------

FidoCadJ can be compiled on an Unix system by using the following command into
the fidocadj/trunk directory:

    ./rebuild
  
FidoCadJ should compile and run. You can use the following script to create 
a jar archive in the jar/ directory:

    ./createjar

3.3 Compile and run the sources on an Windows system
----------------------------------------------------

The provided scripts do not work on Microsoft Windows.
Kohta Ozaki has written a build/run script for Windows, called winbuild.bat. 
It must be used with the action to be accomplished, as an argument:

    run      Launches application
    clean    Deletes all class files under .\bin
    compile  Compiles FidoMain.java and related sources.
             This option refers to the compiler resolving dependency.
    force    Compiles source files of all directories. 
             The compiler starts on each source file. Very slow.
    rebuild  Clean and compile.
    
Alternatively, you might handle manually the compilation with the following
command, in fidocadj\trunk:

    javac  -g -O -sourcepath src -classpath bin -source 1.5 -target 1.5 .\src\FidoMain.java -d bin

to launch the compiled program, you should type:

    java  -classpath .\bin;.\jar;.\jar\  FidoMain

FidoCadJ should start.

3.4 Coding conventions
----------------------

The following coding conventions have been applied for the FidoCadJ source 
code:

- the code should be compatible with Java 1.5
- tab set to 4 spaces
- blocks delimited by curly braces are indented as follows:

    for(i=0; i<10; ++i) {   // starting brace here
        // indented code (4 spaces)
        System.out.println("I counted up to "+i);
    }   // close brace here at the same level of the 'for'
    
- methods are indented as follows:

    void dummy (int i, int j) 
    {   // put the starting brace here
        System.out.println("Indent code");
    }   // put the closing brace here

- the class names always start with a capital letter, and so does methods
- variables never start with a capital letter
- an instance of the class does have its first letter in lower case
- public classes and methods should be documented with Javadoc syntax
- no lines longer than 80 characters
- commits should not break the build
- each commit *MUST* include a log 
- predilect simplicity to unnecessary complication
- predilect quality to quantity
- discuss what you want to do BEFORE start coding
- documentation is important. Try to improve it and keep it up-to-date


3.5 Automatic tests
-------------------

To ease the maintain of a certain degree of quality control when working 
on the source code, the FidoCadJ source repository comes with a number of 
automatic tests scripts contained in the directory test/.
You may launch all the tests by using the script all_tests.sh contained
in this directory, or you may run the tests individually by browsing the
sub-directories containing them. The program is called by using the 
fidocadj.jar archive which must be contained in the jar/ directory. 
Ensure that this archive is updated with the ./createjar script before
launching any test.
The following table briefly describes the provided tests:

  Test                             Comments
  ----------------------------------------------------------------------------
  test/all_test.sh                 Run all the available tests.

  test/export/test_export.sh       Test the export on all available
                                   file formats. A set of reference 
                                   files is provided, so it might be
                                   updated if differences on the 
                                   export are introduced by purpose.
                                   If a test is failed, this tells just that
                                   the exported file is not identical to the
                                   model which has been used. You may have a 
                                   look at the log file and at the result of 
                                   the export. You may decide that it is ok.

  test/messages/test_messages.sh   Test the coherence of all 
                                   installed interface languages against the 
                                   reference (which is the italian resource
                                   file!)

  test/size/test_size.sh           Test if the size calculated for all 
                                   elements is the same as the one stored
                                   as a reference. Any change to the way
                                   the size is calculated will invalidate
                                   the test if the size is invalid.

Note that the way those tests are written, they compare the results of an
operation involving FidoCadJ with a reference. In some cases, the reference
can be improved or updated.
In other cases, the differences might just contain unmeaningful data (such
as version numbers and so on). 

3.6 Static code analysis and the quality of the FidoCadJ source code
--------------------------------------------------------------------

Static code analysis is a powerful tool to ensure code quality. It can not do
miracles, but it is an useful way to avoid common errors. Two tools are 
routinely used to ensure that FidoCadJ is of the highest quality possible.
They are PMD and FindBugs:

http://pmd.sourceforge.net
http://findbugs.sourceforge.net

Those programs are different and somewhat complementary.
PMD works on the source files directly (see the pmd.sh script) and the results
are contained in the file fidocadj_pmd.html. This file is contained in the
source file repository and it provides a sort of a traceable metric of the
overall code quality.

FindBugs runs interactively and analyzes the jar file resulting after the 
compilation and packaging.
The great care applied to the code quality has made sort that FidoCadJ has
had some good results in a quality assessment analysis done by researchers
working in the Department of Computer Science of the University of 
Saskatchewan:

http://www.cs.usask.ca/documents/techreports/2013/TR-2013-01.pdf

If you work on FidoCadJ code, please do all your best to keep high the quality
of the code you are writing.

----------------
4 - Help wanted!
----------------

I am seeking for people interested in participating to the FidoCadJ project.
If you spot a typo (I am not a native English speaker), or an error in the 
manual or in the program, any correction is very welcome. I will be very happy 
to know what do you think about FidoCadJ. I would be glad to receive some 
help: if you know Java and you want to work on the source code you will be 
welcome.
If your Java coding is not fluent, you can participate to the project by 
improving the manuals or translating the interface, or just giving an advice. 
Feel free to contact me at davbucciNOPE@tiscali.it, or in the SourceForge 
forums (the email address is valid without the nope part, but no 
attachments, please). It is probably better to open a discussion in the 
SourceForge forums, in order that the work can eventually be shared and
organized between all developers:

http://sourceforge.net/p/fidocadj/discussion/997486/

4.1 "I want to translate FidoCadJ in my language"
-------------------------------------------------

FidoCadJ is written in such a way that translating its interface is 
particularly easy and does not need any programming skill.
If you have downloaded the source file repository, you should find the 
interface resource files in the trunk/bin directory.
A language resource file has the name MessagesBundle_xx.properties, where
xx is the code for the language to which the translation is targeted.
Language code should follow ISO 639-1:

http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

If you have a look at the beginning of the file 
trunk/bin/MessagesBundle_en.properties, you should read something as 
follow:

    File = File
    New = New
    Open = Open file
    Save = Save
    SaveName = Save as...
    Export = Export
    Print = Print
    Close = Close

    ...

The resources strings are organized in the form key = value. For example,
here is the head of the corresponding file for the interface in French, in 
the file trunk/bin/MessagesBundle_fr.properties

    File = Fichier
    New = Nouveau dessin
    Open = Ouvre un fichier
    Save = Enregistrer
    SaveName = Enregistrer sous un autre nom
    Export = Exporter
    Print = Impression
    Close = Fermer

    ...

That is all. If you want to translate FidoCadJ in your language, you just have
to translate line by line the values in a language resource file, name it 
accordingly to your locale and place it in the trunk/bin directory.
Pay attention that sometimes there are spaces at the end of the value 
strings which need to be kept in place. You may be careful about always 
providing complete files, since if a resource is missing, FidoCadJ can abort. 

4.2 "I would like to participate to the coding activity"
--------------------------------------------------------

This is very nice from you. We will be happy for that. You can manifest 
yourself on the SourceForum forums dedicated to FidoCadJ and declare what are
your skills and basically what you would like to do. We will discuss a little
in order to see if we can find an intersection between what you can do with 
the FidoCadJ development strategy. The idea is to keep the work a little bit 
organized and to know who does what. Have a peek to section 3.3 of this 
README file to see what coding style should be applied to the sources.
Apart from that, FidoCadJ is GPL v.3 and this means that if you have the mood
for, you can download with SVN the source files and play *as you want* with
them. But keep in mind that if you want your contributions be included in the
FidoCadJ main stream, you MUST keep in touch with us in the SF forums and you
must discuss about what are you willing to do. 

Once you decide what you want to do, you can run the Javadoc utility in order
to get a HTML description of all classes used in FidoCadJ. You will find that
useful to understand the underpinnings of the program. To do that, you can
run the trunk/createdoc.sh script, if you are in a Unix system.

Then comes the hard work... We can help you! Please come to the SourceForge
forums dedicated to FidoCadJ!

4.3 Things to do
----------------

----------------------------------------------------------------------------
Review on SourceForge or OhLoh    It is important that the users and 
                                  developers of FidoCadJ understand what is 
                                  good and what is bad in their favorite 
                                  software. Do not be shy to review FidoCadJ 
                                  on SourceForge or OhLoh!
----------------------------------------------------------------------------
Translate user interface          Everything is done on FidoCadJ to make it 
                                  easy to translate its interface in any 
                                  language. You can significatively 
                                  contribute to the spread of FidoCadJ in 
                                  your country!
----------------------------------------------------------------------------
Translate manual                  This is an hard work, but it will be very 
                                  welcomed by the users of your country. You 
                                  will probably need an idea on how LaTeX
                                  works.
----------------------------------------------------------------------------
YouTube video tutorial            I will put on the FidoCadJ's page a link to 
                                  the best video tutorials about FidoCadJ on 
                                  YouTube. Why don't you give it a try?
----------------------------------------------------------------------------
Report bugs                       Use the bug and artifact tracking system of
                                  SourceForge or drop me an email.
----------------------------------------------------------------------------
Export in Gerber format           Exporting in graphical vector formats is 
                                  easy with FidoCadJ. If you want to add a 
                                  file format you just need to know it and 
                                  implement a Java interface. Gerber is 
                                  highly requested by people working on 
                                  PCBs.
----------------------------------------------------------------------------
Export in WMF/EMF formats         WMF/EMF are widely used in Windows and they 
                                  may be useful for including drawings in 
                                  vector format in Microsoft Word or Power 
                                  Point.
----------------------------------------------------------------------------
Linux packaging                   FidoCadJ could be distributed as a deb or
                                  a RPM package. Can you prepare one?
----------------------------------------------------------------------------


--------------------
5 - I found a bug...
--------------------

Every program contains bugs and FidoCadJ is not an exception. Even if all 
the people involved in the development of FidoCadJ pay a lot of attention
at each release, some details could just go unnoticed.
If you ar familiar with the SourceForge interface, do not hesitate to
fill a bug report at the following address:

https://sourceforge.net/p/fidocadj/bugs/

If you feel uncomfortable with the SourceForge system, please drop a few 
lines to davbucciNOPE@tiscali.it

-------------------
6 - Acknowledgments
-------------------

Code: 
    Davide Bucci, josmil1, phylum2, Kohta Ozaki, dantecpp

Beta testers: 
    Stefano Martini, F. Bertolazzi, Emanuele Baggetta, Celsius,
    Andrea D'Amore, Olaf Marzocchi, Werner Randelshofer, Zeno Martini,
    Electrodomus, IsidoroKZ, Gustavo, Kagliostro
    
    ... and many others!

Translations: 
    Davide Bucci (it, en, fr), Pasu (en), Olaf Marzocchi (ge), 
    Geo Cherchetout (fr), androu1 (es), sbcne (es), Miles Qin "qhg007" (zh),
    DirtyDeeds (en), chokewood (nl), Kohta Ozaki (ja), Chemik582 (cs),
    Pietro Baima (it), simo85 (es)
    
Libraries:
    Lorenzo Lutti, Fabrizio Mileto, DirtyDeeds, Electrodomus, IHRaM group

Code snippets included in FidoCadJ:
    http://www.centerkey.com/java/browser/
    http://www.cse.unsw.edu.au/~lambert/splines/natcubic.html
    http://jroller.com/santhosh/entry/enhanced_scrolling_in_swing
    http://www.thoughtsabout.net/blog/archives/000044.html
    http://www.javareference.com/jrexamples/viewexample.jsp?id=99
    http://elliotth.blogspot.com/2004/09/cocoa-like-search-field-for-java.html
    http://stackoverflow.com/questions/3775694/deleting-folder-from-java
    
When possible, the authors of the snippets have been contacted to gain explicit
permission of using the code in an open source project. If you own the 
copyright of some of the reused code and you do not agree on its inclusion in 
the FidoCadJ project, contact us via the SourceForge forum and we will remove
the offending code as fast as we can.

-------------
7 - Licensing
-------------

FidoCadJ is distributed with the GPL v. 3 license:

    FidoCadJ is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    FidoCadJ is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with FidoCadJ.  If not, see <http://www.gnu.org/licenses/>.
