[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

This is an old revision of the document!


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/slackdoc_templates.

You can download single files from the github site or clone the complete repository by issuing the following command in the terminal while logged in as a non-root user.

user@darkstar$ git clone git://github.com/mfillpot/slackdoc_templates.git

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 is included with the git repo files to give 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 this article.

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 git repo listed above contains a vim syntax file that will enable syntax highlighting for all syntax that is used by the Slackware Documentation Project wiki.

The file slackdocs.vim that is contained in the syntax_files directory contains all necessary syntax highlighting criteria for the wiki documents.

Installing the vim Syntax File

To ease installation of the syntax file, the script named add_vim_file.sh is included in the syntax_file directory of the git repo. This script, when launched from that directory, does the following:

  1. Removes all lines that contain the word slackdocs from your ~/.vimrc file.
  2. Adds the following lines to the end of the ~/.vimrc file:
  " Add a pointer to the $FILETYPE vim syntax file
  au BufRead,BufNewFile *.slackdoc set filetype=slackdocs
  au! Syntax slackdocs source {repo_directory}/syntax_files/slackdocs.vim
  

This process removes any old configuration for the .slackdoc extension and updates it with the current configuration.

You can alternatively add it to the standard syntax file location and turn the syntax on automatically, but the automatic option is more user friendly.

If updates are made to the repo based syntax file you can update the repo by issuing the command “git pull” from within the repo directory and re-run the add_vim_file.sh to update your ~/.vimrc file.

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.

Sources

 slackdocs:offline_editing ()