[ktechlab] doc/en: Fixes and updates for handbook
Yuri Chornoivan
null at kde.org
Sun Jan 1 19:46:50 UTC 2017
Git commit 4c7ded5b7dde62273744f620faf9b85b036fa671 by Yuri Chornoivan.
Committed on 01/01/2017 at 19:45.
Pushed by yurchor into branch 'master'.
Fixes and updates for handbook
M +4 -4 doc/en/circuits.docbook
M +19 -36 doc/en/faq.docbook
M +3 -3 doc/en/flowcode.docbook
M +6 -7 doc/en/index.docbook
M +1 -1 doc/en/microbe.docbook
M +3 -3 doc/en/picprograms.docbook
M +3 -3 doc/en/quick.docbook
https://commits.kde.org/ktechlab/4c7ded5b7dde62273744f620faf9b85b036fa671
diff --git a/doc/en/circuits.docbook b/doc/en/circuits.docbook
index 6f72d393..2fcf4097 100644
--- a/doc/en/circuits.docbook
+++ b/doc/en/circuits.docbook
@@ -4,7 +4,7 @@
<sect1 id="placing_components">
<title>Placing components</title>
- <para>On the left, you'll find the Components tab.</para>
+ <para>On the left, you'll find the <guilabel>Components</guilabel> tab.</para>
<para>Dragging a component from the sidebar into the circuit will place it under the mouse cursor. Alternatively, you can double click on an item in the Components sidebar to repeatedly add it to the circuit. In this mode, a copy of the selected component will be placed repeatedly on mouse left-clicking until either Escape is pressed, or the mouse is right-clicked.</para>
@@ -15,13 +15,13 @@
<sect1 id="connecting_components">
<title>Connecting Components</title>
- <para>There are two modes for creating connections (wires): automatic, and manual. These modes are selected via the "Connection Routing Mode" pulldown menu in the toolbar. Experiment with both - automatic routing is often better for small circuits, whereas more complex circuits may need manual routing.</para>
+ <para>There are two modes for creating connections (wires): automatic, and manual. These modes are selected via the <guimenu>Connection Routing Mode</guimenu> pulldown menu in the toolbar. Experiment with both - automatic routing is often better for small circuits, whereas more complex circuits may need manual routing.</para>
<para>In automatic mode, create a connection by dragging from either a component pin or an existing connection, and releasing the mouse over the desired pin or connection. You'll see the straight-line being drawn turn orange when a valid connection will be created on mouse release. If the line you're drawing is black, it's either because there's nothing beneath the mouse cursor, or you're attempting to connect together two items which are already connected. When flowcharting, the criteria for a valid connection are more complex - but we'll get to that later.</para>
<para>The best way to get a feel for manual connection routing is by experimenting with it. Click on the starting pin or connection, and then extend the proto-connector by moving the mouse away from where you clicked. To place a corner, left-click. To cancel drawing the connection, either press escape, or right-click the mouse.</para>
- <para>&kappname; tries its best to maintain the routes your connections take. However, if dragging a component results in the end points of a connection moving relative to each other, &kappname; will be forced to redraw the connection using auto-routing. Before moving a component, you can see which connectors will have to be rerouted - as they will turn grey on clicking.</para>
+ <para>&ktechlab; tries its best to maintain the routes your connections take. However, if dragging a component results in the end points of a connection moving relative to each other, &ktechlab; will be forced to redraw the connection using auto-routing. Before moving a component, you can see which connectors will have to be rerouted - as they will turn grey on clicking.</para>
<para>To remove an existing connection, select it by drawing a small select-rectangle over part of the connector, and hit delete.</para>
</sect1>
@@ -62,7 +62,7 @@
<para>For voltage and current probes, the range of input values can be adjusted in the "Item Editor" sidebar on the right.</para>
- <para>Zooming is controlled by a slider. The scaling is logarithmic; for every few pixels that the slider moves along, the zoom factor will be multiplied by a constant. &kappname; simulates logic to a maximum precision of 1 microsecond, and at maximum zoom level, one microsecond is represented by 8 pixels.</para>
+ <para>Zooming is controlled by a slider. The scaling is logarithmic; for every few pixels that the slider moves along, the zoom factor will be multiplied by a constant. &ktechlab; simulates logic to a maximum precision of 1 microsecond, and at maximum zoom level, one microsecond is represented by 8 pixels.</para>
<para>When the scrollbar is dragged to the end, it will remain there as new data is recorded. Otherwise, the position of the scrollbar remains fixed in time. The oscilloscope view can also be moved forwards and backwards by left-clicking and dragging the view. Due to limitations of the underlying widget system, scrolling will be very granular at maximum zoom.</para>
diff --git a/doc/en/faq.docbook b/doc/en/faq.docbook
index be8b354d..da64a982 100644
--- a/doc/en/faq.docbook
+++ b/doc/en/faq.docbook
@@ -5,63 +5,46 @@
<qandaset>
<qandaentry>
<question>
- <para>Configure can't find gpsim</para>
+ <para>CMake cannot find gpsim</para>
</question>
<answer>
- <para>Configure will attempt to compile several files to test for gpsim presence; testing for versions 0.21.4, 0.21.11 and 0.21.12. These files uses part of the gpsim API, that is also used by &kappname;, and was introduced in the respective gpsim versions. If it fails in compiling this program, it will display the warning to the user, and PIC simulation support will not be compiled into &kappname;. There are a number of possibly reasons for finding gpsim to fail:</para>
+ <para>CMake will attempt to compile several files to test for gpsim presence; testing for versions 0.21.4, 0.21.11 and 0.26. These files uses part of the gpsim API, that is also used by &ktechlab;, and was introduced in the respective gpsim versions. If it fails in compiling this program, it will display the warning to the user, and PIC simulation support will not be compiled into &ktechlab;. There are a number of possibly reasons for finding gpsim to fail:</para>
<itemizedlist>
- <listitem><para>gpsim >= 0.21.4 is not installed. &kappname; does not support gpsim-0.21.2 or gpsim-0.20.14 (or any earlier versions). Later versions may work; but this cannot be tested before they are released. The latest gpsim can be obtained from the <ulink url="http://www.dattalo.com/gnupic/gpsim.html">gpsim website</ulink>.</para></listitem>
- <listitem><para>Gpsim is installed, but the header files could not be found. If gpsim is installed in a non-standard location, you may need to specify the location of the header files with "./configure --with-extra-includes=DIR". It is also likely you'll need to specify a library location with the configure option "--with-extra-lib" if the includes are in a non-standard location.</para></listitem>
- <listitem><para>Gpsim is installed and the headers are somewhere where configure can find them, but there is some other glib craziness occurring.</para></listitem>
+ <listitem><para>gpsim >= 0.21.4 is not installed. &ktechlab; does not support gpsim-0.21.2 or gpsim-0.20.14 (or any earlier versions). Later versions may work; but this cannot be tested before they are released. The latest gpsim can be obtained from the <ulink url="http://gpsim.sourceforge.net/gpsim.html">gpsim website</ulink>.</para></listitem>
+ <listitem><para>Gpsim is installed, but the header files could not be found. If gpsim is installed in a non-standard location, you may need to specify the location of the header files with <command>cmake</command> <option>-DGPSim_INCLUDE_DIR=<replaceable>DIR</replaceable></option>. It is also likely you'll need to specify a library location with the CMake option <quote>GPSim_INCLUDE_DIR</quote> if the includes are in a non-standard location.</para></listitem>
+ <listitem><para>Gpsim is installed and the headers are somewhere where CMake can find them, but there is some other glib craziness occurring.</para></listitem>
</itemizedlist>
- <para>Configure generates the file <computeroutput>config.log</computeroutput> which will contain details of exactly what went wrong. Searching for gpsim in this log should help you decide what's happened. As an example, here is part of the config.log file where one of the gpsim header files is missing:</para>
+ <para>CMake generates the file <filename>CMakeError.log</filename> which will contain details of exactly what went wrong. Searching for gpsim in this log should help you decide what's happened. As an example, here is part of the <filename>CMakeError.log</filename> file where one of the gpsim header files is missing:</para>
- <example><title>Possible config.log output where gpsim detection failed</title>
+ <example><title>Possible CMakeError.log output where gpsim detection failed</title>
<programlisting>
-configure:30956: checking for gpsim 0.21.4 availability
-configure:31009: g++ -c -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
--DQT_THREAD_SUPPORT -O3 -march=athlon-xp -mcpu=athlon-xp -D_REENTRANT
-conftest.cc >&5
-conftest.cc:48:35: gpsim/gpsim_interface.h: No such file or directory</programlisting>
+Building CXX object CMakeFiles/cmTryCompileExec4251549203.dir/src.cxx.o
+/usr/share/colorgcc/c++ -DHAVE_GPSIM_0_26 -fexceptions -I/usr/lib64/glib-2.0/include -o CMakeFiles/cmTryCompileExec4251549203.dir/src.cxx.o
+-c /home/user/playground-devtools/ktechlab/build/CMakeFiles/CMakeTmp/src.cxx
+/home/user/playground-devtools/ktechlab/build/CMakeFiles/CMakeTmp/src.cxx:1:33: fatal error: gpsim/pic-processor.h: No such file or directory
+ #include <gpsim/pic-processor.h>
+ ^
+compilation terminated.</programlisting>
</example>
- <para>If the config.log doesn't help, please contact the &kappname; developers with the relevant parts of config.log attached.</para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question>
- <para>&kappname; crashes when running a PIC program</para>
- </question>
-
- <answer>
- <para>Version 0.21.11 of gpsim contains a bug that may cause &kappname; to crash on the second running of a PIC program. This bug has since been fixed in gpsim-cvs. The &kappname; website provides a <ulink url="http://ktechlab.org/download/gpsim.php">patched version</ulink> of the stable release of gpsim that fixes this bug.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>High Level Language (HLL) debugging does not work</para>
- </question>
-
- <answer>
- <para>Version 0.21.11 of gpsim contains a bug preventing HLL debugging from working. This bug has since been fixed in gpsim-cvs. The &kappname; website provides a <ulink url="http://ktechlab.org/download/gpsim.php">patched version</ulink> of the stable release of gpsim that fixes this bug.</para>
+ <para>If the <filename>CMakeError.log</filename> does not help, please contact the &ktechlab; developers with the relevant parts of <filename>CMakeError.log</filename> attached.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>&kappname; uses lots of CPU</para>
+ <para>&ktechlab; uses lots of CPU</para>
</question>
<answer>
- <para>There are several possible causes. Simulation of circuits that contain both reactive and nonlinear components (such as capacitors and transistors) take a lot of CPU time to simulate. You can pause and resume the simulation via the Tools menu.</para>
+ <para>There are several possible causes. Simulation of circuits that contain both reactive and nonlinear components (such as capacitors and transistors) take a lot of CPU time to simulate. You can pause and resume the simulation via the <guimenu>Tools</guimenu> menu.</para>
- <para>Drawing of the work area (in particular, redrawing lots of rapidly updating voltage bars on pins) is also CPU intensive. You can reduce the refresh rate or turn off the voltage bars via the Settings dialog. The refresh rate of the Oscilloscope can also be reduced by right clicking on its display.</para>
+ <para>Drawing of the work area (in particular, redrawing lots of rapidly updating voltage bars on pins) is also CPU intensive. You can reduce the refresh rate or turn off the voltage bars via the <guilabel>Settings</guilabel> dialog. The refresh rate of the <guilabel>Oscilloscope</guilabel> can also be reduced by right clicking on its display.</para>
- <para>Note that the next major release of &kappname; will be a lot faster in both displaying the work area and simulating reactive and nonlinear components.</para>
+ <para>Note that the next major release of &ktechlab; can be a lot faster in both displaying the work area and simulating reactive and nonlinear components.</para>
</answer>
</qandaentry>
</qandaset>
diff --git a/doc/en/flowcode.docbook b/doc/en/flowcode.docbook
index 6f74dbb0..dbef18e0 100644
--- a/doc/en/flowcode.docbook
+++ b/doc/en/flowcode.docbook
@@ -5,10 +5,10 @@
<sect1 id="flowcode_introduction">
<title>Introduction</title>
- <para>&flowcode; allows for very quick and easy construction of a PIC program. After the user has constructed a flowchart from the program parts available, &kappname; can then convert the flowchart into a number of formats. To output hex, for example, the following chain of conversions takes place:</para>
+ <para>&flowcode; allows for very quick and easy construction of a PIC program. After the user has constructed a flowchart from the program parts available, &ktechlab; can then convert the flowchart into a number of formats. To output hex, for example, the following chain of conversions takes place:</para>
<orderedlist>
- <listitem><para>The &flowcode; is converted to µbe;; a high-level language whose compiler is distributed with &kappname;.</para></listitem>
+ <listitem><para>The &flowcode; is converted to µbe;; a high-level language whose compiler is distributed with &ktechlab;.</para></listitem>
<listitem><para>The <command>microbe</command> executable then compiles the µbe; file to PIC assembly.</para></listitem>
<listitem><para>Finally, <command>gpasm</command> takes the PIC assembly file, and outputs the hex for the program.</para></listitem>
</orderedlist>
@@ -20,7 +20,7 @@
<sect1 id="flowcode_creation">
<title>Creating a Program</title>
- <para>Every &flowcode; program needs a unique starting point - this is the place where your program will be run from on PIC startup. To define this point, open up the FlowParts sidebar on the left, and drag across the Start part. &kappname; will only allow you to use one of these.</para>
+ <para>Every &flowcode; program needs a unique starting point - this is the place where your program will be run from on PIC startup. To define this point, open up the FlowParts sidebar on the left, and drag across the Start part. &ktechlab; will only allow you to use one of these.</para>
<para>You can then construct your program by using the predefined parts on the left - or insert code of your own (in assembly or µbe; format) via the Embed part. The flow of the program is controlled via the connections between the FlowParts - <xref linkend="connecting_components"/> offers more detail on creating connections.</para>
diff --git a/doc/en/index.docbook b/doc/en/index.docbook
index db8f7e2d..4f0d6336 100644
--- a/doc/en/index.docbook
+++ b/doc/en/index.docbook
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<!-- kate: tab-width 2; indent-mode xml; -->
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
- <!ENTITY ktechlab "ktechlab">
+ <!ENTITY ktechlab "KTechlab">
<!ENTITY ktechlab-quick SYSTEM "quick.docbook">
<!ENTITY ktechlab-pic-programs SYSTEM "picprograms.docbook">
<!ENTITY ktechlab-circuits SYSTEM "circuits.docbook">
@@ -9,16 +9,15 @@
<!ENTITY ktechlab-microbe SYSTEM "microbe.docbook">
<!ENTITY ktechlab-debugging SYSTEM "debugging.docbook">
<!ENTITY ktechlab-faq SYSTEM "faq.docbook">
- <!ENTITY kappname "KTechlab">
<!ENTITY microbe "Microbe">
<!ENTITY flowcode "FlowCode">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
]>
-
+
<book lang="&language;">
<bookinfo>
- <title>The KTechlab Handbook</title>
+ <title>The &ktechlab; Handbook</title>
<authorgroup>
<author>
<firstname>David</firstname>
@@ -30,8 +29,8 @@
<surname>Clarke</surname>
</author>
</authorgroup>
- <date>2005-12-27</date>
- <releaseinfo>0.3</releaseinfo>
+ <date>2017-01-01</date>
+ <releaseinfo>0.3.6</releaseinfo>
<abstract>
<para>KTechlab is an IDE for microcontrollers and electronics.</para>
</abstract>
@@ -45,7 +44,7 @@
<keyword>Microbe</keyword>
</keywordset>
</bookinfo>
-
+
&ktechlab-quick;
&ktechlab-pic-programs;
&ktechlab-circuits;
diff --git a/doc/en/microbe.docbook b/doc/en/microbe.docbook
index 203ceb88..853d2b82 100644
--- a/doc/en/microbe.docbook
+++ b/doc/en/microbe.docbook
@@ -4,7 +4,7 @@
<sect1>
<title>Introduction and General Syntax</title>
<para>
- <application>Microbe</application> compiles programs written in the custom language for PICs, as a companion program to <application>&kappname;</application>. The syntax has been designed to suit a &flowcode; program.
+ <application>Microbe</application> compiles programs written in the custom language for PICs, as a companion program to <application>&ktechlab;</application>. The syntax has been designed to suit a &flowcode; program.
The syntax for running <command>microbe</command> from the commandline is:
diff --git a/doc/en/picprograms.docbook b/doc/en/picprograms.docbook
index 858e75a7..03ab43a6 100644
--- a/doc/en/picprograms.docbook
+++ b/doc/en/picprograms.docbook
@@ -10,7 +10,7 @@
<itemizedlist>
<listitem><para>Convert to µbe; - This is used only in &flowcode; documents. This is explained further in <xref linkend="flowcode"/>.</para></listitem>
- <listitem><para>Convert to Assembly - This can be used in four contexts. When a &flowcode; document is open, it will output the &flowcode; as assembly instructions. When a µbe; document is open, it will invoke the <command>microbe</command> program distributed with &kappname; to compile the program. Similarly, if a C program is open, it will attempt to compile it via SDCC. When a text document containing PIC hex is open, it will invoke <command>gpdasm</command> to disassemble the hex.</para></listitem>
+ <listitem><para>Convert to Assembly - This can be used in four contexts. When a &flowcode; document is open, it will output the &flowcode; as assembly instructions. When a µbe; document is open, it will invoke the <command>microbe</command> program distributed with &ktechlab; to compile the program. Similarly, if a C program is open, it will attempt to compile it via SDCC. When a text document containing PIC hex is open, it will invoke <command>gpdasm</command> to disassemble the hex.</para></listitem>
<listitem><para>Convert to Hex - This can also be used in four contexts. As with Convert to Assembly, this can be used with &flowcode;, µbe; and C documents. It will also be enabled when an assembly document is open to assemble it via <command>gpasm</command>.</para></listitem>
@@ -19,13 +19,13 @@
<para>None of these actions require the current document to be saved - very useful for when a quick program is required. For non-PIC targets, the Output Dialog invoked on clicking on one of these actions can either output the result (always text in the above three cases) to a fresh document, or to a file. If the output is saved to file, it also provides options to load the file after creation, and adding the newly created file to the open project (if one is open).</para>
- <para>Note that you can make &kappname; always use the same view for displaying the outputted content by selecting the option under General Settings.</para>
+ <para>Note that you can make &ktechlab; always use the same view for displaying the outputted content by selecting the option under General Settings.</para>
</sect1>
<sect1 id="uploading">
<title>Uploading</title>
- <para>&kappname; uses third-party programmers to upload programs to PICs. A variety of common programmers come predefined. Others can be added via the Settings dialog. See the <ulink url="http://ktechlab.org/pic_programmers.php">&kappname; website</ulink> for more information.</para>
+ <para>&ktechlab; uses third-party programmers to upload programs to PICs. A variety of common programmers come predefined. Others can be added via the Settings dialog. See the <ulink url="http://ktechlab.org/pic_programmers.php">&ktechlab; website</ulink> for more information.</para>
<para>The list of ports is obtained from scanning for serial and parallel ports that are readable and writable. Serial ports are looked for in:</para>
<itemizedlist>
diff --git a/doc/en/quick.docbook b/doc/en/quick.docbook
index 0cf7f293..d13e4a69 100644
--- a/doc/en/quick.docbook
+++ b/doc/en/quick.docbook
@@ -5,14 +5,14 @@
<sect1 id="introduction">
<title>Introduction</title>
- <para>&kappname; is an IDE for electronic circuits and microcontrollers. It can perform simulation a variety of components (logic, integrated, linear, nonlinear and reactive), simulation and debugging of PIC microcontrollers via gpsim, and comes with its own closely-linked and complementary high level languages: &flowcode; and µbe;.</para>
+ <para>&ktechlab; is an IDE for electronic circuits and microcontrollers. It can perform simulation a variety of components (logic, integrated, linear, nonlinear and reactive), simulation and debugging of PIC microcontrollers via gpsim, and comes with its own closely-linked and complementary high level languages: &flowcode; and µbe;.</para>
<para>It has been designed to be as easy to use and unintrusive as possible; all components and FlowParts have context sensitive help, and simulating electronics is as simple as dragging components onto the work area and creating connectors that autoroute themselves between their pins. &flowcode; allows users new to PICs to instantly create their own programs, while the electronic simulation allows stepping through a PIC's assembly program inside a circuit.</para>
</sect1>
<sect1 id="documents">
<title>Documents</title>
- <para>To get started in &kappname;, you will need to create a new document, whose type will depend on your task:</para>
+ <para>To get started in &ktechlab;, you will need to create a new document, whose type will depend on your task:</para>
<itemizedlist>
<listitem><para>&flowcode; Document - Construct a PIC program via flowcharting.</para></listitem>
@@ -21,7 +21,7 @@
<listitem><para>Assembly Document - Start writing a PIC assembly program.</para></listitem>
</itemizedlist>
- <para>&kappname; uses a Document-View model, in that the Document logic is completely separate from open views of the document. This allows several views of the same file.</para>
+ <para>&ktechlab; uses a Document-View model, in that the Document logic is completely separate from open views of the document. This allows several views of the same file.</para>
<para>On creating a new document, the view is created in a separate tab. Each tab can support any number of views, tiled in any arbitrary pattern. This allows, for example, simulating a PIC program in circuit, while stepping through the program in an assembly document in the same tab.</para>
More information about the kde-doc-english
mailing list