Documents

This section describes how the create and work with documents. For documents shared on the WWW see the section World Wide Web.

They are many philosophies how to write documents:

  1. The most known is WYSIWYG (What You See Is What You Get) or some programs do WYSIAWYG (What You See Is Almost What You Get).

  2. An other goal that is on contradiction to the above is: Write a document once and use it everywhere. This concept allows you to have a version that you or a team of authors access where you can have an version control system. It can be exported to a web page in HTML so it can be read using a browser. Or exported to pdf to be sent everywhere and printed on paper.

Acrobat

The newest version (2017 Version 10) of Acrobat reader is not available under Linux. Working with older binary versions that require old libraries is not very recommended.

okular is a good alternative that depends on some but not too many kde libraries.

ghostview is also an option to view pdf files and postscript files. Ghostview can also be used to create pdf files:

  1. Print to a postscript file using a postscript printer driver

  2. Create the pdf file by calling: ps2pdf<my file>.ps

There is Gsview a viewer for postscript. To edit pdf's pdf's can be opened with gimp, important is to set landscape or portrait correctly before importing the pdf. You can select multiple pages, but every page becomes a gimp layer.

To modify pdf files or to combine scanned in single pages there are:

  1. A command line tool pdftk https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/

    See the https://www.pdflabs.com/docs/pdftk-cli-examples/ to get the examples that you probably want as: Merge two or more pdfs into a new document pdftk 1.pdf 2.pdf 3.pdf cat output 123.pdf. pdfchain is a gui for pdftk

  2. A gui tool jpdftweak java gui http://jpdftweak.sourceforge.net/

  3. mupdf pdfmod are other alternatives

Emacs

As a Linux beginner I avoided emacs, since it looks old fashioned, ugly and bloated. However I ended up with many specialized editors: OpenOffice Writer, editor that come with the desktop environment, Lyx, HTML editors, … .

Instead of learning all those tools, it might be better to replace them by emacs. Since emacs is more than just an editor, it is more something as an IDE: It can be used to write and debug many things as c programs, xslt, bashdb and many more.

The emacs user interface is really not intuitive. Middle mouse clicks are used instead of double clicks and some keystrokes have to be known, even there is a gui. Open files are buffers, in the Buffers menu they can be closed. Alt+x (or Esc+x) makes M-x in the command line below. Add the following here: M-x fundamental-mode to get the major mode fundamental. Luckily the tab key completes text. There is also Crtl+x that is C+x. F1 + M gives a description about the active major modes.

There are two versions to choose from http://www.gnu.org/software/emacs/ (looks better) and http://www.xemacs.org (looks really ugly and old fashioned). Gentoo solves this by having a virtual emacs ebuild and a eselect-emacs ebuild. Emerge the emacs of your choice or both of them and do a eselect emacs list to see what you have got. And to switch between them.

Emacs was mainly written in lisp. You might come in touch with lisp when you do advanced things with emacs.

LibreOffice

Libre Office is a fork from Open Office and is a free alternative to Microsoft Office. It runs under Linux but also under Windows. The latest versions can smoothly open Microsoft files and store them in then various Microsoft file formats as well. However it is more future oriented to store them in a open format. By the way,LibreOffice can also be used to help Microsoft Office users to open their files when they run in incompatibility problems.

Luckily, standards for the public are in preparation (Microsoft is involved, but probably due to the pressure received ) to define the file formats for office files. See http://www.ecma-international.org/ where TC45 - Office Open XML Formats creates the standard ECMA-376 that will be adopted by www.iso.org and www.iec.ch and will create an other incompatibility to Microsoft Office.

If you want to open a LibreOffice file on a Windows computer that hasn't LibreOffice installed you should look at https://portableapps.com/ where you find OpenOffice portable for Windows, that runs from your memory stick and does not need to be installed on the Windows computer.

Try to close and save open office files when you make some tests with device drivers and multimedia.

If you have a crash and you can not open a file anymore, you might consider to unzip the crashed LibreOffice file, a directory will appear where you might recover some data with XML format.

Calc

Insert Name Define => creates cell name other than e.g. A7 so constants can be picked from cells and used in formulas, without being overwritten by increments when copying.

Writer

A very good and comprehensive guide can be found here: http://www.linuxtopia.org/online_books/office_guides/openoffice_writer_user_guide/index.html

Table of contents

Go to Tools => Outline Numbering to create numbers for titles (not other numberings as line numbering). This way you can create table of contents based on outline.

Once having set the outline numbering, inserting the table of contains goes as expected:

Insert => Indexes and Tables => Table of Contents

To have Hyperlinks in the table of context right click table of contents then select Edit Index/Table to get a menu. There go in the Entries tab. What then follows is a rather complicated procedure that can be read using the LibreOffice help.

Alphabetical index

Select the word that you want to have in the index then

Insert => Indexes and Tables => Entry and click to Insert (Using the default settings the word should be getting a gray background). Repeat until you are happy then click to close. Click there where you want to have the index and Insert => Indexes and Tables => Indexes and Tables. Select Alphabetical Index and click OK. To have two columns in the alphabetic index and save lots of pages do edit index table and set 2 columns.

Formatting

Do not just select text and modify it with font, size color since this would be badly maintainable. Go in Format=>Styles and Formatting a window opens. To format text there are Paragraph Styles and Character Styles. Paragraph Styles format everything until a CR character whereas Character Styles can be used to highlight a single word embedded in text.

Note: Don't activate numbering for headings (Chapter titles), since this is done via Tools => Outline Numbering

In this document I used custom styles to have all command lines using this style. If I find they are too small to big or can not be printed black and withe, I can change on a single location and do not have to scan manually throughout the document and do hundreds (or even thousands) of mouse clicks.

The manually caused formatting mess can be cleaned by selecting each manually formatted item individually and Mouse click right=>Default Formatting. This is an other reason why working with styles should be started right at the beginning.

When making a manual page break the page style of the following page can be selected. First page for the first and last page to create the cover, default page for the rest has been used in this document.

Tips

If AutoComplete is activated LibreOffice proposes some text before you have finished the typing, you can accept it by pressing the Enter key.

Pictures or other stuff can have captain assigned that allows to give them a visible title and border.

Ugly icons

Change the icon style found under Tools>Options>View

Draw

  1. To make holes into a shape use combine.

  2. To make complex shapes rectangular with round section draw them individually and then use merge shapes.

  3. Don't do it with more than 2 shapes at a time.

  4. To change the value of dimension, just select the dimension and type in what you like to see.

Latex

Lot of Linux tools make use of latex (pronounced like laitech), so you might get in contact with it and think is is old fashioned. You might get it confirmed when observing the latest release date.

Figure 9.1. Latex

Latex


This section gives a short overview. https://www.latex-project.org/

jedit might be a good editor.

Similar to docbook, latex allows writing documents using a regular ASCII editor. Such files have tex extension and use its own syntax to make the text attributes (docbook uses XML for that). Latex can convert such tex files to dvi files that can be viewed (xdvi or kdvi) or converted to Postscript using divps. Latex can not be used on its own it requires something as a latex distribution containing fonts, and tools. Latex can be converted to HTML using latex2html or tex4ht or pdf using pdflatex.

Lyx

To not edit latex with an ASCII editor, Latex has a GUI front end lyx that stores its data in files with lyx extension. Lyx has a nice web page and a wiki:

http://www.lyx.org/

http://wiki.lyx.org/

Lyx has it own file extension *.lyx but allows latex source preview and latex export.

Lyx can be used for all kind of things. Start lyx go to the help menu and start reading.

If you want something other than English just change the language.

Start lyx from a console so you see what is going on.

If dvi preview does not run, try to open via file manager a dvi file to find out the name of a program that can do it. In xfce4 there is probably already evince installed that can do the job. To tell lyx to use evince as dvi viewer set it via Tools > Preferences > File Handling > File Format. Then select dvi and instead of auto set evince (or whatever name the dvi viewer has).

When you type, the characters go into an environment. The environment defines what the characters mean: Is it simple text, is it a title, a list, a comment, ….

To convert into html lyx makes use of latex2html, see http://www.eng.cam.ac.uk/help/tpl/textprocessing/latex2html/manual.html. A successor is tex4ht http://tug.org/applications/tex4ht/ . As can be seen under Preferences > File handling > Converters the call to latex2html is set as:

latex2html -no_subdir -split 0 -show_section_numbers $$i

This causes to create a single HTML page. To have multiple pages either modify it to:

latex2html -no_subdir -show_section_numbers $$i

Or set a split value bigger than 0.

Wiki

https://www.wikipedia.org/ has demonstrated the success of wiki. Wiki uses its own markup language that is then converted into HTML to be shown using regular web browsers. Regular HTML browsers allow also to edit the text.

The term wikitext or wiki markup is used for the source of wiki. Wikitext is considered as simplified markup. There was no standard at the beginning to define wiki markup and some incompatibilities occurred.

A wiki software (wiki application or wiki engine) is used for the conversation. There are also creole to xhtml converters.

Depending on the wiki software the data is stored in regular files or in a database as mysql (and since images do not fit in the database, there are even some files in a filesystem when using the database approach):

  1. http://www.dokuwiki.org/ is a wiki that does not use a database.

  2. https://www.mediawiki.org/wiki/MediaWiki is the fully blown wiki used by wikipedia that uses a database as mysql.

It is strongly recommended to consider how to backup your wiki, especially when you want to edit it on the web and give others permission to do so. Also security issues have to be considered. Making a backup of a full blown database based wiki is much more complicated than using a filesystem based wiki. If you read “I lost my wiki database”, then this means all the work is gone.

There are incredible many different wiki's checkout http://www.wikimatrix.org/ what wikis exist and what they can do and require.

The standard way is to convert wiki data into HTML, however wiki data might get also exported to other formats as pdf or xml.

Dokuwiki

http://www.dokuwiki.org/ uses a directory where the stuff goes and does not use a database. It is therefore easier for the backup and has a lot of plugins that can expand its functionality. File synchronizers as unison can be used to synchronize and backup dokuwiki when it is present on the machine or the wiki files can be accessed via a file system.

To install dokuwiki under gentoo and having apache

http://www.dokuwiki.org/install:gentoo

php needs to be installed. Before emerging dokuwiki it must be decided how it should be installed. Two ways exist just install to one server or when your PC has multiple virtual servers, just install it beside under /usr/share/webapps and link it to the virtual servers making use of it. If virtual servers are used, this is more recommended since it is flexible and future oriented, so set the vhosts useflag. When the vhost useflag is set, then emerge dokuwiki.

To use it, it must be (hard)linked to the virtual host used:

webapp-config -I -h <host> -d dokuwiki dokuwiki 20120125

<host> can be localhost or any other name of a host used.

The defaults should work, but you might want to adapt the main configuration file:

/var/www/localhost/htdocs/dokuwiki/conf/dokuwiki.php

However you should not modify too much there, since it is considered to hold working default values and might be overwritten by updates of dokuwiki. Create instead your /var/www/localhost/htdocs/dokuwiki/conf/local.php file, by copy the example

cp local.php.dist local.php and do the modifications there.

Now it is time to check your dokuwiki put the following into your browser

http://localhost/dokuwiki/doku.php?do=check

Verify that users.auth.php has write permission, since this is to register users.

The do parameter can also be used for other things (action modes) as

http://localhost/dokuwiki/doku.php?do=export_html

http://localhost/dokuwiki/doku.php?do=export_raw

After that you can start editing the top page

http://localhost/dokuwiki/

To create additional pages just create a link in the top page to the new page. Then click on the link and dokuwiki ask you to edit the newly created page.

Where the data goes

The pages are stored as wiki text files in: /var/www/localhost/htdocs/dokuwiki/data/pages

and the pictures are in

/var/www/localhost/htdocs/dokuwiki/data/media

Inside those two directories, other subdirectories can be created. This will be namespaces, that hold sub-dokuwikies. To make a link to them just use <namespace>:<pagename>.

When manually created such directories (make sure that have the same access rights and ownership) or when page got moved manually to such subpages, delete all files in /var/www/localhost/htdocs/dokuwiki/data/attic and in /var/www/localhost/htdocs/dokuwiki/data/metadata.

Additionally the links to pictures must be updated inside every page.

Nice looking links

Since dokuwiki has to create the HTML pages dynamically from the wiki text. Depending on the server setup, the links can look rather ugly as:

http://localhost/dokuwiki/doku.php?id=photography

To have them as:

http://localhost/dokuwiki/doku.php/photography

Modify

/var/www/localhost/htdocs/dokuwiki/conf/local.php

to:

$conf['userewrite'] = 2; //this makes nice URLs: 0: off 1: .htaccess 2: internal$conf['userewrite'] = 2;

Alternatively the web server (as apache) could be reconfigured to get rid of the doku.php characters in the link.

Security

The default settings are quite open and lets everybody editing pages. ACL (Access Control Lists) are used to login users and prevent that everybody can edit the wiki.

Create the files by copy the defaults:

cp users.auth.php.dist users.auth.php

cp acl.auth.php.dist acl.auth.php

and give it the right ownership

chown apache:apache users.auth.php acl.auth.php

and modify /var/www/localhost/htdocs/dokuwiki/conf/local.php

$conf['useacl'] = 1; //Use Access Control Lists to restrict access?

Note a login button appears now on the wiki page.

The dokuwiki can send out the password via mail. To have this work, you have to verify that apache can send emails. Since apache probably runs as root, root need to be able to send emails.

If you don't want to enable this emailing you can

$conf['autopasswd'] = 0; //autogenerate passwords and email them to user

After that you can register yourself directly.

To delete a user delete its entry in /var/www/localhost/htdocs/dokuwiki/conf/users.auth.php

Doku wiki plugins

Plugins allow to expand dokuwiki, there is the Configuration Manager Plugin that deals with that (instead of installing plugins manually). It updates

/var/www/localhost/htdocs/dokuwiki/conf/local.php. It is installed by default, but you need to login and your name must match the entries in /var/www/localhost/htdocs/dokuwiki/conf/local.php:

$conf['superuser'] = '<myname>'; //The admin can be user or @group or comma separated list user1,@group1,user2

$conf['manager'] = '<myname>'; //The manager can be user or @group or comma separated list user1,@group1,user2

Make sure the /var/www/localhost/htdocs/dokuwiki/lib/plugins directory can be written.

http://www.dokuwiki.org/plugin:composer

Export to static HTML

http://www.dokuwiki.org/plugin:dokukiwix

http://www.dokuwiki.org/plugin:offline

or to pdf

http://www.dokuwiki.org/plugin:dw2pdf

http://www.dokuwiki.org/plugin:html2pdf

other plugins are for statistics, support of multimedia, ...


Linurs Servernest startpage