Abandon AsciiDoc in favor of plain HTML

It is very difficult to set up Python or Ruby on Windows XP.

Simple HTML works better, everywhere, it covers all our needs,
and it isn't any harder to write.

This documentation is now installed.
This commit is contained in:
Přemysl Eric Janouch 2021-10-24 23:58:52 +02:00
parent 924617e1ce
commit ada833a009
Signed by: p
GPG Key ID: A0420B94F92B9493
6 changed files with 282 additions and 294 deletions

View File

@ -390,6 +390,7 @@ else (WIN32)
install (FILES LICENSE NEWS DESTINATION share/doc/${PROJECT_NAME}) install (FILES LICENSE NEWS DESTINATION share/doc/${PROJECT_NAME})
endif (WIN32) endif (WIN32)
install (DIRECTORY docs/user-guide DESTINATION share/doc/${PROJECT_NAME})
install (DIRECTORY share/gui share/library DESTINATION share/${PROJECT_NAME}) install (DIRECTORY share/gui share/library DESTINATION share/${PROJECT_NAME})
install (FILES ${GSETTINGS_SCHEMAS} DESTINATION share/glib-2.0/schemas) install (FILES ${GSETTINGS_SCHEMAS} DESTINATION share/glib-2.0/schemas)
install (CODE " # DESTDIR is not in use on Windows (WIN32 is only native here!) install (CODE " # DESTDIR is not in use on Windows (WIN32 is only native here!)

View File

@ -0,0 +1,7 @@
body { max-width: 50em; margin: 0 auto 4em auto; padding: 0 2em;
font-family: sans-serif; } h1, h2, h3 { font-weight: normal; }
h1 { font-size: 2.5em; } h2 { font-size: 2em; } h3 { font-size: 1.33em; }
h2 { padding-top: .67em; border-top: 1px solid silver; }
p { line-height: 1.5; } .figure { text-align: center; } img { max-width: 100%; }
q { font-style: normal; } .details { border-bottom: 1px solid silver; }
.details br { display: none; } .details br + span:before { content: " — "; }

View File

@ -1,148 +0,0 @@
// TODO: nakonfigurovat v CMake asciidoctor-pdf, je potřeba pár `gem install`
// https://github.com/asciidoctor/asciidoctor-pdf/blob/master/README.adoc
// https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc
logdiag: Průvodce uživatele
===========================
Přemysl Eric Janouch <p@janouch.name>
v0.2.0, 2018-06-27
:toc: left
:toc-title: Obsah
:sectnums:
:warning-caption: VAROVÁNÍ
:xrefstyle: short
:figure-caption: Obrázek
image::logdiag-cs.png[]
<<<
Úvod
----
Tento dokument vás má za účel provést po aplikaci a pomoci vám se v ní
zorientovat. Popis úkonů se přednostně vztahuje na operační systém Microsoft
Windows, do jisté míry je však platný i pro jiné operační systémy.
Získání aplikace
----------------
Nejnovější verzi aplikace je možné stáhnout na následující webové adrese:
https://git.janouch.name/p/logdiag.
[[gitea-download]]
.Nabídka pro stahování na stráncách projektu
image::gitea.png[]
Až se ocitnete na webu, vyhledejte v záhlaví záložku s nápisem ``Releases'' a
klepněte na ni. Zobrazí se přehled vydání a pod hlavičkami ``Downloads''
související soubory ke stažení. Instalační soubor pro Microsoft Windows nese
název ve stylu ``logdiag-__verze__-Windows-x86.exe''.
Instalace
---------
Proces instalace je velmi přímočarý. Po úvodní obrazovce je vyžadován souhlas s
licencí. Pokud nerozumíte anglicky, její stručné shrnutí zní, že aplikaci smíte
v nezměněné formě zcela volně používat a redistribuovat, ale nejsou vám
poskytovány žádné záruky. Následuje výběr složky, do které chcete aplikaci
nainstalovat, a složky pro umístění ve Start menu. V případě, že nenastala žádná
náhlá chyba, už jen stačí potvrdit úspěšnou instalaci.
WARNING: Pokud aplikaci instalujete do složky, kde se nachází již existující
instalace, mohou nastat potíže. Ačkoliv je to možné, nepokoušejte se z těch
samých příčin instalovat ani více kopií vedle sebe. Nejdříve stávající instalaci
odstraňte, například pomocí zástupce umístěného ve Start menu.
Operace s objekty
-----------------
////
TODO: zkusit restrukturalizovat na:
4. Operace s objekty
4.1 Základní operace
4.1.1 Výběr
4.1.2 Přesun
4.1.3 Odstranění
4.2 Značky
4.2.1 Vložení
4.2.2 Otáčení
4.3 Spojení
4.3.1 Tvorba
////
Každý diagram je tvořen z objektů, a s těmi se sdružují dále popsané operace.
Budete-li chtít momentálně prováděnou operaci zrušit, můžete tak obvykle učinit
stiskem klávesy Escape.
Výběr objektů
~~~~~~~~~~~~~
Jednotlivé objekty můžete vybírat levým kliknutím myší. Ty se v reakci na to
vyznačí červenou barvou. Chcete-li vybrat objektů více, držte během klikání
stisknutou klávesu Shift.
// XXX: nelze zarovnat obrázek na střed zároveň s caption
[[select-objects]]
.Výběr objektů v oblasti
image::select-objects.png[]
Alternativně můžete táhnout myší z volné oblasti diagramu do prostoru, viz
<<select-objects>>. Vyberou se objekty obsažené ve vytvořeném obdélníku. Výběr
lze zrušit klepnutím na prázdné místo.
Přesun objektů
~~~~~~~~~~~~~~
Přesun objektů se provede tažením objektů myší na požadované místo. Pokud jsou
tyto objekty součástí výběru, přesune se celý výběr. Ten lze též přesouvat
pomocí kurzorových kláves.
Odstranění objektů
~~~~~~~~~~~~~~~~~~
Objekty odstraníte stisknutím klávesy Delete, případně z menu aplikace.
Vložení značky
~~~~~~~~~~~~~~
_Značky_ představují nejdůležitější druh objektů. Do diagramu je vložíte výběrem
z nabídky značek umístěné po levé straně hlavního okna aplikace a přetažením
myší do diagramu na požadované umístění.
Otáčení značek
~~~~~~~~~~~~~~
Otočit značku vloženou do diagramu můžete přes pravé tlačítko myši.
Propojení terminálů
~~~~~~~~~~~~~~~~~~~
_Terminálem_ se nazývá bod určený pro tvorbu spojení mezi značkami nebo jinými
spojeními. Abyste z něj spojení vyvedli, nejdříve na něj najeďte kurzorem myši
tak, aby se viditelně vyznačil kroužkem. Pak stiskněte levé tlačítko myši a
přetáhněte kurzor myši na místo, kde chcete, aby spojení končilo.
// XXX: nelze sloučit do jedné figure
[[create-connection]]
.Propojení terminálů dvou značek
image:create-connection-begin.png[]
&nbsp;...&nbsp;
image:create-connection-end.png[]
Časté problémy
--------------
Nelze otevřít uložený diagram
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Při ukládání se ujistěte, že zadaný název souboru obsahuje příponu ``.ldd''. V
opačném případě se nezobrazí v dialogu pro otevření diagramu. Pokud jste nějaký
soubor již bez přípony uložili, napravíte to dodatečným přidáním přípony k jeho
názvu.
Jak můžu diagram vytisknout?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Současná verze aplikace není schopná přímo tisknout. Pro vytištění vytvořeného
diagramu můžete klávesou PrintScreen sejmout snímek obrazovky, vložit jej
například do aplikace Malování, oříznout požadovanou část a vytisknout ji z
tohoto grafického editoru.
Schází mi popisky
~~~~~~~~~~~~~~~~~
Obdobně jako v předchozím případě tato funkcionalita zatím neexistuje, ale je
možné tento nedostatek obejít přes běžný grafický editor.

View File

@ -0,0 +1,141 @@
<!DOCTYPE html>
<html lang="cs">
<head>
<meta charset="UTF-8">
<title>logdiag: Průvodce uživatele</title>
<link rel="stylesheet" href="stylesheet.css">
<style>
q:lang(cs):before { content: "„"; }
q:lang(cs):after { content: "“"; }
</style>
</head>
<body>
<h1>logdiag: Průvodce uživatele</h1>
<p class="details">
<span id="author">Přemysl Eric Janouch</span><br>
<span id="email"><a href="mailto:p@janouch.name">p@janouch.name</a></span><br>
<span id="revnumber">verze 0.2.0,</span>
<span id="revdate">2018-06-27</span>
<p class="figure"><img src="logdiag-cs.png" alt="Okno programu logdiag">
<h2>Úvod</h2>
<p>Tento dokument vás má za účel provést po aplikaci a pomoci vám se v ní
zorientovat. Popis úkonů se přednostně vztahuje na operační systém Microsoft
Windows, do jisté míry je však platný i pro jiné operační systémy.
<h2>Získání aplikace</h2>
<p>Nejnovější verzi aplikace je možné stáhnout na následující webové adrese:
<a href="https://git.janouch.name/p/logdiag">https://git.janouch.name/p/logdiag</a>.
<p class="figure"><img src="gitea.png" alt="Gitea">
<br>Obrázek 1: Nabídka pro stahování na stránkách projektu
<p>Až se ocitnete na webu, vyhledejte v záhlaví záložku s nápisem
<q>Releases</q> a klepněte na ni. Zobrazí se přehled vydání a pod hlavičkami
<q>Downloads</q> související soubory ke stažení. Instalační soubor pro Microsoft
Windows nese název ve stylu <q>logdiag-<i>verze</i>-Windows-x86.exe</q>.
<h2>Instalace</h2>
<p>Proces instalace je velmi přímočarý. Po úvodní obrazovce je vyžadován souhlas
s licencí. Pokud nerozumíte anglicky, její stručné shrnutí zní, že aplikaci
smíte v nezměněné formě zcela volně používat a redistribuovat, ale nejsou vám
poskytovány žádné záruky. Následuje výběr složky, do které chcete aplikaci
nainstalovat, a složky pro umístění ve Start menu. V případě, že nenastala žádná
náhlá chyba, už jen stačí potvrdit úspěšnou instalaci.
<p><b>Pozor</b>: Pokud aplikaci instalujete do složky, kde se nachází již
existující instalace, mohou nastat potíže. Ačkoliv je to možné, nepokoušejte se
z těch samých příčin instalovat ani více kopií vedle sebe. Nejdříve stávající
instalaci odstraňte, například pomocí zástupce umístěného ve Start menu.
<h2>Operace s objekty</h2>
<p>Každý diagram je tvořen z objektů, a s těmi se sdružují dále popsané operace.
Budete-li chtít momentálně prováděnou operaci zrušit, můžete tak obvykle učinit
stiskem klávesy Escape.
<!-- TODO: zkusit restrukturalizovat na:
Operace s objekty
Základní operace
Výběr
Přesun
Odstranění
Značky
Vložení
Otáčení
Spojení
Tvorba
-->
<h3>Výběr objektů</h3>
<p>Jednotlivé objekty můžete vybírat levým kliknutím myší. Ty se v reakci na to
vyznačí červenou barvou. Chcete-li vybrat objektů více, držte během klikání
stisknutou klávesu Shift.
<p class="figure" id="select-objects">
<img src="select-objects.png" alt="Výběr objektů">
<br>Obrázek 2: Výběr objektů v oblasti
<p>Alternativně můžete táhnout myší z volné oblasti diagramu do prostoru, viz
<a href="#select-objects">Obrázek 2</a>. Vyberou se objekty obsažené
ve vytvořeném obdélníku. Výběr lze zrušit klepnutím na prázdné místo.
<h3>Přesun objektů</h3>
<p>Přesun objektů se provede tažením objektů myší na požadované místo. Pokud
jsou tyto objekty součástí výběru, přesune se celý výběr. Ten lze též přesouvat
pomocí kurzorových kláves.
<h3>Odstranění objektů</h3>
<p>Objekty odstraníte stisknutím klávesy Delete, případně z menu aplikace.
<h3>Vložení značky</h3>
<p><i>Značky</i> představují nejdůležitější druh objektů. Do diagramu je vložíte
výběrem z nabídky značek umístěné po levé straně hlavního okna aplikace
a přetažením myší do diagramu na požadované umístění.
<h3>Otáčení značek</h3>
<p>Otočit značku vloženou do diagramu můžete přes pravé tlačítko myši.
<h3>Propojení terminálů</h3>
<p><i>Terminálem</i> se nazývá bod určený pro tvorbu spojení mezi značkami nebo
jinými spojeními. Abyste z něj spojení vyvedli, nejdříve na něj najeďte kurzorem
myši tak, aby se viditelně vyznačil kroužkem. Pak stiskněte levé tlačítko myši
a přetáhněte kurzor myši na místo, kde chcete, aby spojení končilo.
<p class="figure" id="create-connection">
<img src="create-connection-begin.png" alt="Začátek operace" align="center">
&nbsp;&#8230;&nbsp;
<img src="create-connection-end.png" alt="Konec operace" align="center">
<br>Obrázek 3: Propojení terminálů dvou značek
<h2>Časté problémy</h2>
<h3>Nelze otevřít uložený diagram</h3>
<p>Při ukládání se ujistěte, že zadaný název souboru obsahuje příponu
<q>.ldd</q>. V opačném případě se nezobrazí v dialogu pro otevření diagramu.
Pokud jste nějaký soubor již bez přípony uložili, napravíte to dodatečným
přidáním přípony k jeho názvu.
<h3>Jak můžu diagram vytisknout?</h3>
<p>Současná verze aplikace není schopná přímo tisknout. Pro vytištění
vytvořeného diagramu můžete klávesou PrintScreen sejmout snímek obrazovky,
vložit jej například do aplikace Malování, oříznout požadovanou část
a vytisknout ji z tohoto grafického editoru.
<h3>Schází mi popisky</h3>
<p>Obdobně jako v předchozím případě tato funkcionalita zatím neexistuje,
ale je možné tento nedostatek obejít přes běžný grafický editor.
<script>
var toc = '', all = document.querySelectorAll('h2')
for (var i = 0; i < all.length; i++) {
var name = all[i].innerHTML.replace(/[^0-9a-z]/ig, '-')
toc += '<li><p><a href="#' + name + '">' + all[i].innerHTML + '</a></li>'
all[i].id = name
all[i].innerHTML = (i + 1) + '. ' + all[i].innerHTML
}
all[0].insertAdjacentHTML('beforebegin',
'<h2>Obsah</h2><ol>' + toc + '</ol>')
</script>

View File

@ -1,146 +0,0 @@
// TODO: nakonfigurovat v CMake asciidoctor-pdf, je potřeba pár `gem install`
// https://github.com/asciidoctor/asciidoctor-pdf/blob/master/README.adoc
// https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc
logdiag: User Guide
===================
Přemysl Eric Janouch <p@janouch.name>
v0.2.0, 2018-06-27
:toc: left
:sectnums:
:xrefstyle: short
image::logdiag-en.png[]
<<<
Introduction
------------
This document will guide you through the application and help to familiarize you
with it. The description of tasks mainly targets the Microsoft Windows
operating system, though it's also valid for other operating systems to
a certain extent.
Getting the application
-----------------------
Download the newest version of the application at the following web address:
https://git.janouch.name/p/logdiag.
[[gitea-download]]
.The download menu on the project site
image::gitea.png[]
While on the web, look for a tab entitled ``Releases'' and click on it. A list
of versions will appear with files for download listed under ``Downloads''
headings. The installation file for Microsoft Windows is named in the style of
``logdiag-__version__-Windows-x86.exe''.
Installation
------------
The installation process is quite straight-forward. After the initial screen a
license agreement is required. Next, choose a folder in which to install the
application and another one for placement in the Start menu. So long as no
unexpected errors have occurred, all that's left is confirming a successful
installation.
WARNING: If the application is installed into a folder where a previous
installation is already located, problems may arise. Although it is possible to
do so, don't try to install multiple copies parallely either, for the same
reasons. Remove the current installation first, for example by using the
shortcut located in the Start menu.
Operations with objects
-----------------------
////
TODO: zkusit restrukturalizovat na:
4. Operace s objekty
4.1 Základní operace
4.1.1 Výběr
4.1.2 Přesun
4.1.3 Odstranění
4.2 Značky
4.2.1 Vložení
4.2.2 Otáčení
4.3 Spojení
4.3.1 Tvorba
////
Each diagram consists of objects, and these are accompanied by the operations
described below. To cancel any current operation, press the Escape key.
Selecting objects
~~~~~~~~~~~~~~~~~
Select single objects by left-clicking on them. They will get highlighted with
red color in reaction to this. To select multiple objects, hold the Shift key
while clicking.
// XXX: nelze zarovnat obrázek na střed zároveň s caption
[[select-objects]]
.Selecting objects inside an area
image::select-objects.png[]
Alternatively drag the mouse from free space within the diagram into the area,
see <<select-objects>>. Objects contained in this rectangle will be
selected. The selection may later be dismissed by just clicking into free space.
Moving objects
~~~~~~~~~~~~~~
Moving of objects is done by dragging them with the mouse onto the desired
place. If these objects form a part of the current selection, the whole
selection is moved. The selection may also be moved using cursor keys.
Removing objects
~~~~~~~~~~~~~~~~
Remove objects either by pressing the Delete key or from the application menu.
Inserting symbols
~~~~~~~~~~~~~~~~~
_Symbols_ constitute the most important kind of objects. Insert them into the
diagram by choosing one from the symbol menu located on the left side of the
main application window and dragging it onto the diagram where you want the
symbol to be placed.
Rotating symbols
~~~~~~~~~~~~~~~~
Rotate a symbol inserted into the diagram by right-clicking on it.
Connecting terminals
~~~~~~~~~~~~~~~~~~~~
A point intended for creation of connections between symbols or other
connections is called a _terminal_. To lead a connection out of it, first
hover it with the mouse pointer, so it gets visibly highlighted with a circle.
Then press the left mouse button and drag the pointer onto the place where you
want the connection to end.
// XXX: nelze sloučit do jedné figure
[[create-connection]]
.Interconnecting terminals of two symbols
image:create-connection-begin.png[]
&nbsp;...&nbsp;
image:create-connection-end.png[]
Frequent problems
-----------------
Can't open a saved diagram
~~~~~~~~~~~~~~~~~~~~~~~~~~
When saving, ensure that the filename you've typed in contains the ``.ldd''
suffix. If not, it won't show up in the dialog for opening diagrams. In case
you've already saved a file without an extension, you may fix this situation by
adding the suffix to its name.
How do I print a diagram?
~~~~~~~~~~~~~~~~~~~~~~~~~
The current version of application is not able to print directly. To print out a
created diagram, you may use the PrintScreen key to capture a screenshot, then
insert it to, for example, Paint, and print it from inside the graphics editor.
I miss labels
~~~~~~~~~~~~~
Similarly to the previous case, this functionality doesn't exist yet, but it is
possible to get around this limitation using a graphics editor.

View File

@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>logdiag: User Guide</title>
<link rel="stylesheet" href="stylesheet.css">
<style>
q:lang(en):before { content: ""; }
q:lang(en):after { content: ""; }
</style>
</head>
<body>
<h1>logdiag: User Guide</h1>
<p class="details">
<span id="author">Přemysl Eric Janouch</span><br>
<span id="email"><a href="mailto:p@janouch.name">p@janouch.name</a></span><br>
<span id="revnumber">version 0.2.0,</span>
<span id="revdate">2018-06-27</span>
<p class="figure"><img src="logdiag-en.png" alt="logdiag program window">
<h2>Introduction</h2>
<p>This document will guide you through the application and help to familiarize
you with it. The description of tasks mainly targets the Microsoft Windows
operating system, though its also valid for other operating systems to
a certain extent.
<h2>Getting the application</h2>
<p>Download the newest version of the application at the following web address:
<a href="https://git.janouch.name/p/logdiag">https://git.janouch.name/p/logdiag</a>.
<p class="figure"><img src="gitea.png" alt="Gitea">
<br>Figure 1: The download menu on the project site
<p>While on the web, look for a tab entitled <q>Releases</q> and click on it.
A list of versions will appear with files for download listed under
<q>Downloads</q> headings. The installation file for Microsoft Windows is named
in the style of <q>logdiag-<i>version</i>-Windows-x86.exe</q>.
<h2>Installation</h2>
<p>The installation process is quite straight-forward. After the initial screen
a license agreement is required. Next, choose a folder in which to install
the application and another one for placement in the Start menu. So long as
no unexpected errors have occurred, all thats left is confirming a successful
installation.
<p><b>Warning</b>: If the application is installed into a folder where
a previous installation is already located, problems may arise. Although it is
possible to do so, dont try to install multiple copies parallely either, for
the same reasons. Remove the current installation first, for example by using
the shortcut located in the Start menu.
<h2>Operations with objects</h2>
<p>Each diagram consists of objects, and these are accompanied by the operations
described below. To cancel any current operation, press the Escape key.
<!-- TODO: see the Czech version -->
<h3>Selecting objects</h3>
<p>Select single objects by left-clicking on them. They will get highlighted
with red color in reaction to this. To select multiple objects, hold the Shift
key while clicking.
<p class="figure" id="select-objects">
<img src="select-objects.png" alt="select objects">
<br>Figure 2: Selecting objects inside an area
<p>Alternatively drag the mouse from free space within the diagram into
the area, see <a href="#select-objects">Figure 2</a>. Objects contained in this
rectangle will be selected. The selection may later be dismissed by just
clicking into free space.
<h3>Moving objects</h3>
<p>Moving of objects is done by dragging them with the mouse onto the desired
place. If these objects form a part of the current selection, the whole
selection is moved. The selection may also be moved using cursor keys.
<h3>Removing objects</h3>
<p>Remove objects either by pressing the Delete key or from the application
menu.
<h3>Inserting symbols</h3>
<p><i>Symbols</i> constitute the most important kind of objects. Insert them
into the diagram by choosing one from the symbol menu located on the left side
of the main application window and dragging it onto the diagram where you want
the symbol to be placed.
<h3>Rotating symbols</h3>
<p>Rotate a symbol inserted into the diagram by right-clicking on it.
<h3>Connecting terminals</h3>
<p>A point intended for creation of connections between symbols or other
connections is called a <i>terminal</i>. To lead a connection out of it, first
hover it with the mouse pointer, so it gets visibly highlighted with a circle.
Then press the left mouse button and drag the pointer onto the place where you
want the connection to end.
<p class="figure" id="create-connection">
<img src="create-connection-begin.png" alt="Start of operation" align="center">
&nbsp;&#8230;&nbsp;
<img src="create-connection-end.png" alt="End of operation" align="center">
<br>Figure 3: Interconnecting terminals of two symbols
<h2>Frequent problems</h2>
<h3>Cant open a saved diagram</h3>
<p>When saving, ensure that the filename youve typed in contains the
<q>.ldd</q> suffix. If not, it wont show up in the dialog for opening diagrams.
In case youve already saved a file without an extension, you may fix this
situation by adding the suffix to its name.
<h3>How do I print a diagram?</h3>
<p>The current version of application is not able to print directly. To print
out a created diagram, you may use the PrintScreen key to capture a screenshot,
then insert it to, for example, Paint, and print it from inside the graphics
editor.
<h3>I miss labels</h3>
<p>Similarly to the previous case, this functionality doesnt exist yet, but it
is possible to get around this limitation using a graphics editor.
<script>
var toc = '', all = document.querySelectorAll('h2')
for (var i = 0; i < all.length; i++) {
var name = all[i].innerHTML.replace(/[^0-9a-z]/ig, '-')
toc += '<li><p><a href="#' + name + '">' + all[i].innerHTML + '</a></li>'
all[i].id = name
all[i].innerHTML = (i + 1) + '. ' + all[i].innerHTML
}
all[0].insertAdjacentHTML('beforebegin',
'<h2>Table of Contents</h2><ol>' + toc + '</ol>')
</script>