This is an old revision of the document!
Table of Contents
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.
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.
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.
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:
- Removes all lines that contain the word slackdocs from your ~/.vimrc file.
- 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.
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.