[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.

Welcome to the Slackware Documentation Project

Offline Wiki Editing

Why Edit Offline?

The nature of a wiki based system is to have the documentation avaiable online, but there will be times when you will want or need to edit an article outside of the WYSIWYG editor on the website such as:

  • When writing a new article
  • Editing a large article
  • Translating an article

Starting a New Article Offline

The most basic way to start working on a new article offline is to open your favorite text editor and start writing. However, when pasting the contents of your article into the wiki you will need to paste the data inside of the template.

As an alternative, a git repo (listed below) has been established with template files for each of the major sections within the wiki. You can start with the template file to guarantee that the header and footer data is retained.

Obtaining Existing Wiki Pages

If you wish to edit an existing page, you will first need to download the ofiginal markup formatted text from the page, fortunately dokuwiki has a built-in function to ease the trouble.

When in a webbrowser looking at the page you will need to append the syntax ?do=export_raw to the end of the url such as http://docs.slackware.com/slackware:current?do=export_raw.

For translators it may be a good idea to save the links of documents that you are converting and append the syntax above to the end of the urls so wget can loop through the list obtaining new copies of each file.

If you want to go the more traditional route, you can open the wiki page and click the edit this page button to access the WYSIWYG interface, then copy the contents to a local text file.

Offline Editing

To simplify your editing needs, the slackdocs editorial team has a git repository that contains the following:

  • all template files
  • a brief overview of the dokuwiki syntax
  • instructions to enable syntax highlighting in various text editors

This repository is located at https://github.com/mfillpot/slackdoctool

If you wish to build a package from the github repo you can find an associated slackbuild script set at https://github.com/mfillpot/mfillpot_SlackBuild_Scripts/tree/sdt/office/slackdoctool

The script has many functions that can be reviewed by issuing the -l argument or viewing the man file.

Once the template files are downloaded you can open the appropriate template file with your favorite text editor such as vim, emacs, kate, etc.. and add your content.

The file syntax.docuwiki can be downloaded with the -S argument, it will give you brief examples of the dokuwiki syntax that is used by the Slackware Documentation Project.

To simplify editing the docuwiki formatted articles, instructions to enable syntax highlighting in various editors is included in the slackdoctool..

The extension .slackdoc is used for the templates to automatically enable syntax highlighting in the vim text editor.

Syntax Highlighting

With any markup or programming language it can often be difficult to know if your syntax use is correct or if specific text is included within a tag block. To ease this and expedite editing, syntax coloring and syntax highlighting can be enabled in various text editors.

Syntax Highlighting in vim

In the following sections you will find instructions to enable syntax highlighting for slackdoc/dokuwiki contents in various text editors.

vim Syntax Highlighting

To simplify editing in the vim text editor the slackdoctool can download and load the necessary configuration files with the option -s vim.

kate Syntax Highlighting

To implement syntax highlighting to slackdoc articles in kate you need to enable the MediaWiki syntax highlighting by going to:

  • Tools
  • Highlighting
  • Markup
  • Mediawiki

The syntax used between mediawiki and dokuwiki are close enough that it properly represents most syntax.

Submitting the Updated Article(s)

To submit the updated or new articles you will first have to open the article on the wiki in edit this page view, then you can either copy and paste the article into the WYSIWYG editor from your favorite text edit or use xclip to copy the contents from the command line.

Copying from the CLI

Install the xclip application from SlackBuilds.org.

Issue the command

cat {filename} | xclip -selection clipboard

Then the complete document is in your clipboard, you can then paste it into the wiki's WYSIWYG editor.

Alternatively, the slackdoctool can load the documents into the clipboard with the -c argument.

Sources

 slackdocs:offline_editing ()