OBS Logistics

C-Assist User Guide

CALIDUS Assist

25th February 2020 - 0.1
Reference: UG 352360

Creating articles for inclusion in a PDF Book

This page is intended to help with the automated production of PDF Books from the Assist pages.

There are two ways of creating a PDF document:

As a single page
As a book - generated from multiple categorized pages.

Single Page

For a single page, use the templates provided here. These are designed to help you create new pages or documents, using templates to make the documents work properly.

Creation of a Book

Create a title page, as the Document title plus the word "Title" on the end. The page can be created using the template provided. In addition, the footer must be configured on this page, utilising comments. For example:


{{Doc_Title|System=Calidus ''Vision''|Title=Vision Coding and Release|Reference=236343|Version=1.0|Date=9th May 2011}}

Add this and all pages to be printed as part of the PDF book to a category of the same name, for example:


[[Category:Vision Coding and Release Doc|000]]

Note that the Category Sort value should be set to 000 for the title page. All other articles included in the document should have a sort value assigned to them to indicate the position in the document.

If required, create an appendix page. This Template can be used as an example. This page should be named as the document title plus the word "Appendix" on the end. Note that the Category Sort should be set to 999.
Create the Category page as in the following example:


=Vision Coding and Release=
This category encompasses pages that collate technical information of how the system is built and installed.
[{{fullurl:{{FULLPAGENAMEE}}|action=pdfbook&notitle}} Download this selection of articles as a PDF book.]

Production of the PDF

Click the link on the category entry created above, or click the Download/Print as PDF link in the toolbar from the category or from the single page.

Setup Requirements

See Assist PDF Production Code for details, but the PDF Book extension should already have been enabled in all Assist instances for you.

Creating new documents from templates

You can create new documents using the links on the following page:

Create New Page

Creating a new Wiki installation

Warning: This page has been superseded by Assist Upgrade Actions. See there for more information. However, this old version might contain some useful information, so is preserved.

Initial Setup

Copy an existing WIKI folder to a new folder and rename to your Wiki.
In this folder:
- Rename the LocalSettings.php to *.old.php
- Remove config/LocalSettings.php

Configuration

Connect to the site in a browser, and click the 'Set up the Wiki' link to configure and enter all the details required:

Site config

Wiki name: Must not be blank or "MediaWiki" and may not contain "#". Enter the Product name here e.g. WCS, EPOD, TTM, etc
Contact e-mail: Your email address.
Language: en
Copyright/license: No license metadata
Admin username: Usually this is set to <wiki>_owner
Password: Any password you like, but don't forget it. The password cannot be the same as the username.
Object caching: No caching

E-mail, e-mail notification and authentication setup

E-mail features (global): Enabled
User-to-user e-mail: Enabled
E-mail notification about changes: Enabled for changes to user discussion pages, and to pages on watchlists
E-mail address authentication: Enabled

Database config

Database type: MySQL
Database host: localhost
Database name: <wiki>_assist
DB username: <wiki>_owner
DB password: Any password you like, but don't forget it.

Superuser account: Use superuser account if you have it
Superuser name:
Superuser password:

MySQL-specific options

Database table prefix: <wiki>_

Storage Engine: InnoDB
Database character set: MySQL 4.1/5.0 binary

Click the Install MediaWiki button to create the configuration file.

Once complete, copy the config/LocalSettings.php to the root directory of this new wiki.

Further Configuration

Edit the LocalSettings.php file created above and paste the following at the bottom of the file:

# Restrictions
#Restrict anonymous editing
$wgGroupPermissions['*']['edit'] = false;
# Prevent new user registrations except by sysops
$wgGroupPermissions['*']['createaccount'] = false;
# Add permissions to autoconfirmed users
$wgGroupPermissions['creator']['delete'] = true;
$wgGroupPermissions['creator']['autopatrol'] = true;
# True Anonymous access
$wgShowIPinHeader = false;

# Settings for PDFBook
require_once( "$IP/extensions/PdfBook/PdfBook.php" );
$wgPdfBookLeftMargin = "2cm"; 		#Left page margin
$wgPdfBookRightMargin = "2cm"; 		#Right page margin
$wgPdfBookTopMargin = "2cm"; 		#Top page margin
$wgPdfBookBottomMargin = "1cm"; 		#Bottom page margin
$wgPdfBookFont = "Arial";	#Default font to use if unspecified in content
$wgPdfBookFontSize = "11"; 		#Point size of default font
$wgPdfBookLinkColour = "217A28"; 	#Colour to use when rendering hyperlinks in text
$wgPdfBookTocLevels = "2"; 		#Number of outline levels to use when building the table of contents
#$wgPdfBookExclude 	empty 	List of article titles which should not be included in the book

# Settings to get the Help extensions working
require_once( "$IP/extensions/ParserFunctions/ParserFunctions.php" );
#$wgPFEnableStringFunctions = true;
require_once("$IP/extensions/NumberFormat/NumberFormat.php");

# Settings to enable SVG - doesn't work
#$wgFileExtensions[] = 'svg';
#$wgAllowTitlesInSVG = true;

# WikiForum settings
#require_once("$IP/extensions/WikiForum/WikiForum.php");

# Document Approval settings
#require_once("$IP/extensions/DocumentApproval.php");

# MakeArticle settings
require_once("$IP/extensions/makearticle/makearticle.php");

# CreateArticle settings
require_once($IP . "/extensions/CreateArticle.php" );

#Collapsable Text settings
require_once("$IP/extensions/JSpoiler.php");

#UDEF Variables settings
require_once( "$IP/extensions/Variables/Variables.php" );

#WYSIWYG editor
#require_once("$IP/extensions/FCKeditor/FCKeditor.php"); //works but it breaks the Special:Version page

# Settings to get full error details from Wiki
$wgShowExceptionDetails = true;

#Display Webpages in Wikis
include("extensions/anywebsite.php");

$wgCopyrightIcon = "<a href=\"http://www.obs-logistics.com\" target=\"_blank\"><img src='/calidus-assist/WMS/skins/common/images/wiki.png' height=\"40\" alt='OBS Logistics Ltd' /></a>";

# Default User Options for new users:
$wgDefaultUserOptions['forceeditsummary'] = 1;

Change the existing $wgEnableUploads variable to true.

Change the existing $wgDefaultSkin variable to 'vector'.

Change the existing $wgPasswordSender variable to your email address.

Save the LocalSettings.php file.

You can now log on to the new wiki as the admin user you created earlier.

Creating the basic content

Edit MediaWiki:Common.js (index.php?title=MediaWiki:Common.js&action=edit or just search for MediaWiki:Common.js) and add the following:

    mwCustomEditButtons.push({
        "imageFile": "images/Button_enter.png",
        "speedTip": "Line break",
        "tagOpen": "<br />",
        "tagClose": "",
        "sampleText": ""
    });
 
    mwCustomEditButtons.push({
        "imageFile": "images/Button_upper_letter.png",
        "speedTip": "Superscript",
        "tagOpen": "<sup>",
        "tagClose": "</sup>",
        "sampleText": "Superscript text"
    });
 
    mwCustomEditButtons.push({
        "imageFile": "images/Button_small.png",
        "speedTip": "Small",
        "tagOpen": "<small>",
        "tagClose": "</small>",
        "sampleText": "Small Text"
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_gallery.png",
        "speedTip": "Insert a picture gallery",
        "tagOpen": "\n<gallery widths=600px heights=350px perrow=1>\n",
        "tagClose": "\n</gallery>",
        "sampleText": "Image:CTLTMS_Example1.PNG|''Caption1''\nImage:CTLTMS_Example2.PNG|''Caption2''"
    });

    var today = new Date();
    var monthNames = ["January", "February", "March", "April", "May", "June",
      "July", "August", "September", "October", "November", "December"
    ];
    var stndrdth = ["th","st","nd","rd","th","th","th","th","th","th"];
    var dayth = today.getDate() % 10;
    mwCustomEditButtons.push({
        "imageFile": "images/Button_CoverPage.png",
        "speedTip": "Insert an Document Title Page",
        "tagOpen": "{{Doc_Title\n|Client=ClientName\n|System=''CALIDUS'' System\n|Title=Doc Title\n|Reference=Document type and Supimix reference\n|Version=0.1\n|Date="+today.getDate()+stndrdth[dayth]+" "+monthNames[today.getMonth()]+" "+today.getFullYear()+"\n|Year="+today.getFullYear()+"\n}}\n",
        "tagClose": "",
        "sampleText": ""
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_LastPage.png",
        "speedTip": "Insert an Document Final Page",
        "tagOpen": "{{Doc_Appendix|\nAppendix=The Appendix Section. Defaults to A\n|Glossary=WCS|WMS|CTMS. Omit if no glossary is to be included.\n|Ref1=First reference document title. There can be up to 5 (Ref2, Ref3, etc). Omit those you do not want to use.\n|RefV1=First reference document version\n|RefDate1=First reference document date\n|Rev1=Authorising Name. Up to 3 may be specified (Rev2, Rev3)\n|Rev1Title=Job Title\n",
        "tagClose": "\n}}\n",
        "sampleText": "<!-- The following may also be added -->\n|Estimate=Enter Y if an estimate section is to be included. Use the following fields for the values. If the values are omitted, they default to Zero. Also include Client and Year for the correct rates.\n|REQ=Requirements Time\n|EST=Estimate Time\n|FS=Functional Specification Time\n|TS=Technical Specification Time\n|DEV=Development Time\n|ST=Testing Time\n|IMP=Implementation Time\n|Client=Client for estimate rates\n|Year=Year for estimate rates"
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_blockquote.png",
        "speedTip": "Insert an Estimate template",
        "tagOpen": "{{EstimateCostDetails\n|REQ=Requirements Days\n|EST=Estimation Days\n|FS=Functional Specification Days\n|TS=Technical Specification Days\n|DEV=Development Days\n|ST=Testing and Release Days\n|IMP=Implementation Days\n|Client=Client for charges|Year=Year for charges}}\n",
        "tagClose": "",
        "sampleText": ""
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_test_header.png",
        "speedTip": "Insert a test plan template",
        "tagOpen": "{{TestPlan_Header\n|Title=Title of test plan\n|Log=Supimix log reference\n|Description=description of what is to be achieved\n|MenuAccess=Where on the menus the item can be found\n|Prerequisites=The prerequisites of the test\n|Objective=The details of what each group of tests is to achieve\n}}\n{{ #vardefine: Cycle | 0 }}{{ #vardefine: SubCycle | 0 }}\n{{TestPlan_CycleHeader\n|Cycle={{ #vardefineecho: Cycle | {{ #expr: {{ #var: Cycle }} + 1 }} }}{{ #vardefine: SubCycle | {{ #var: Cycle }} }}\n|Title=Area being tested in this cycle\n|Notes=Any notes or prerequisites for the tests following.\n}}\n",
        "tagClose": "\n{{TestPlan_CycleFooter}}\n",
        "sampleText": "<!--INSERT TESTS HERE -->"
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_test_header.png",
        "speedTip": "Insert a test plan cycle",
        "tagOpen": "{{TestPlan_CycleHeader\n|Cycle={{ #vardefineecho: Cycle | {{ #expr: {{ #var: Cycle }} + 1 }} }}{{ #vardefine: SubCycle | {{ #var: Cycle }} }}\n|Title=Area being tested in this cycle\n|Notes=Any notes or prerequisites for the tests following.\n}}\n",
        "tagClose": "\n{{TestPlan_CycleFooter}}\n",
        "sampleText": "<!--INSERT TESTS HERE -->"
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_test_add.png",
        "speedTip": "Insert a new test",
        "tagOpen": "{{TestPlan_Test\n|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.1 }} }}\n|Action=The actions to follow\n|Result=The expected result\n}}\n",
        "tagClose": "",
        "sampleText": ""
    });

    mwCustomEditButtons.push({
        "imageFile": "images/Button_insert_table.png",
        "speedTip": "Insert a table",
        "tagOpen": '{| class="wikitable" border="1"\n|- bgcolor="silver"\n',
        "tagClose": "\n|}\n",
        "sampleText": "! header1 !! header2 !! header3\n|-\n| cell1 || cell2 || cell3"
    });


    mwCustomEditButtons.push({
        "imageFile": "images/Button_comment.png",
        "speedTip": "Insert a comment",
        "tagOpen": '{{comment|text=',
        "tagClose": "\n|sign=[[User:"+wgUserName+"]]|date="+today.getDate()+"/"+(today.getMonth()+1)+"/"+today.getFullYear()+" "+today.getHours()+":"+today.getMinutes()+":"+today.getSeconds()+"}}\n",
        "sampleText": "Your Comment Here"
    });

Edit MediaWiki:Vector.js (index.php?title=MediaWiki:Vector.js&action=edit or just search for MediaWiki:Vector.js) and add the following:

window.onload = function (e) {
  document.getElementById('mw-panel').style.position='fixed';
}

Export the following pages and files from an existing Wiki:

Pages

Template:Note
Template:Warning
Template:Meta
Template:Clear
Template:Hl2
Template:Hl3
Template:Prettytable
Template:!
Template:Comment
Template:Doc_Appendix
Template:Doc_Title
Template:EstimateCostDetails
Template:TestPlan_CycleFooter
Template:TestPlan_CycleHeader
Template:TestPlan_Header
Template:TestPlan_Test
Template:Estimate_Head
Template:WCS_Glossary
Template:WMS_Glossary
Template:EPOD_Glossary
Template:CTMS_Glossary
Template:FS
Template:Estimate
Template:REQ
Template:DocLink
Help:Contents
Help:PDF_Book
Help:CreateNewPage

Files:

OBS_Logistics_Logo.JPG
Bulbgraph.png
Attention_niels_epting.png

Import the pages into the new Wiki through the Special:Import page.

Upload the images into the new Wiki through the Special:Upload page.

The Wiki should now be ready for use.

Creating Users

Create users using Email - they will then become autoconfirmed users.

Any users you don't want to track edits (i.e. non-patrolled), add them to the Creator group.

Upgrading the version of an existing Wiki installation

Warning: This page has been superseded by Assist Upgrade Actions. See there for more information. However, this old version might contain some useful information, so is preserved.

Note: The latest validated version of MediaWiki that works with Assist is 1.16.5.

Note: Although later versions may work, it is expected that the PDF export (required for most of the Assist pages) will eventually break, due to CSS being introduced in more modern versions.

Software Required

MySQL Administrator (root access)
php (part of MediaWiki)
The full MediaWiki archive file, from here:
- Current versions: https://www.mediawiki.org/wiki/Download
- Old versions: https://releases.wikimedia.org/mediawiki/

Prior to Upgrade

Back up the database schema being affected.
Back up the installation for the wiki being upgraded.

Upgrade

Full upgrade instructions related to your version of MediaWiki are in the folder as a file called UPGRADE. Follow these instructions

Essentially it involves running

php /maintenance/upgrade.php

Note: php is part of MediaWiki. you may need to directly point to the php exe in the main MediaWiki folder.

Note: Ensure that the <wiki>_owner account has full access to create and alter schema properties, or updates will fail.

Editing a document

General

Before editing, you should log in - the Assist system will not allow you to edit the documents unless you have, so that all changes can be tracked to the user that made them.

Document Editing

When you find a page that needs editing, you can do it in one of to ways:

Source Editing - typing in plain text with WikiText markup language - not too complicated, but a bit of a barrier for new users. Click the Edit Source button to start source editing.
Visual Editing - like a simple version of your favourite document editing application. You can do most things (but not all) with Visual Editing. Click the Edit link against a page to start Visual Editing.

You can also flip between visual and source editing when you're in there, so don't worry if you clicked the wrong one.

This guide will show you how to do everything here in each of the editing methods, to help reduce those barriers and make documentation easier.

Source Editing

WikiText markup can seem daunting, but it's not meant to be. This guide won't try and describe everything that you can do with WikiText markup, but will describe how the tools can make it easier to do.

This section will introduce you to the source editing toolbar and some basic concepts.

When source editing you will have a toolbar for basic edits. So start typing, and when you want to format something, you can use the toolbar.

If I want something in bold, I click the Bold Text button - the WikiText markup will be put in the editing window for me, with the text in between the markup ready for editing.

The same is true for:

Italic text
Headings (level 2-5)
Bulleted lists (like this one) or

Numbered list items like this one

No Wiki formatting (turns off WikiText markup, hugely useful when writing a guide like this one!)
New Line
Big text or Small text
^{Superscript text} or _{Subscript text}
Links to other pages, like Did You Know.
Code.
"Noinclude" tags.

You can also highlight the text you want to format and then click the button - the editor will tag the text you highlighted.

You have a Preview button - this shows you what you're WikiText changes look like in real formatting in near real time. You can't edit it there. but it's useful to see you're getting it right.

Other essential page formatting is more complicated:

Tables can be inserted easily enough using the Table button. Click the button, choose your number of columns and rows (and any properties of the table, like sortable) and click Insert. The editor will insert the table for you in shorthand, like below:

Caption text
Header text	Header text	Header text
Example	Example	Example
Example	Example	Example
Example	Example	Example

Then you can edit it. We typically do not use captions, so you could remove that line if you want. To change the cell content, simply change the text between the vertical bars (or exclamation points, if it's the header row).

Tables also support being searchable - it's not a property that is supported by the Table tool, so you have to edit it in yourself.

Add "apt-searchable" to the table class

 {| class="wikitable apt-searchable"

You can then make rows non-searchable by adding a class to the row "|-" element as follows:

 |- class="non-searchable"

Images are covered in a following section.

Visual Editing

Visual editing formats the text like it would do on the final page (in most cases). It's almost completely invisible to you as an editor that in the background this is generating the WikiText markup for you, so makes it much easier. There are however some things that the Visual Editor can't do which source editing is very useful for.

This section will introduce you to the visual editing toolbar and some basic concepts.

When visual editing you will have a toolbar for basic edits. So start typing, and when you want to format something, you can use the toolbar or the provided shortcuts.

If I want something in bold, I click the Style Text button and choose Bold or press CTRL-B - the text I type will be in bold from now on. You can turn it off in the same way.

Note: The visual editor can use keyboard shortcuts, and the editor will tell you the shortcut keys next to the toolbar option you are selecting, if there is one.

Standard shortcut keys are also supported, like cut/copy/paste:

CTRL-X - Cut.
CTRL-C - Copy.
CTRL-V - Paste (formatted).
CTRL-SHIFT-V - Paste (plain text).

Additional formatting:

CTRL-I - Italic text
Big text or Small text
^{Superscript text} or _{Subscript text}
Computer code formatting
CTRL-U - Underline

and many more.

You can also highlight the text you want to format and then click the button - the editor will tag the text you highlighted.

Similarly with links to other pages, like Did You Know. Either click the Links button in the toolbar, enter the page name and click Done. You then have the opportunity to edit alternative text directly over the link. The same is true for an existing link when you click on it.

Bullets and numbered lists (and indentation) can be accessed from the Structure button.

Bulleted lists (like this one). There's no shortcut key, but you can start a bulleted list by entering an asterisk followed by a space.

Numbered list items like this one. There's no shortcut key, but you can start a numbered list by entering a number followed by a full stop and a space. Or a hash symbol followed by a space for a new numbered list.

Paragraph formatting can be accessed from the Paragraph Formatting drop-down list in the toolbar.

Headings (level 2-5)
Preformatted Code formatting
Centre text

and many more.

Warning: You currently can't mark anything as nowiki formatting, or as noinclude. Sorry - you have to use the Source Editor for that.

You have undo and redo buttons (and their normal shortcut keys (CTRL-Z and CTRL-Y).

If you are familiar with WikiText markup and start typing in the syntax from WikiText (like {{ to insert a template), the Visual Editor is going to recognise that and either format the text or popup the dialogue associated to that WikiText markup - in the example above, it will open up the Insert Template dialogue for you, so the markup can be used as shortcuts in most cases. It doesn't work for bold and italic or images, but pretty much for everything else, so handy to know.

If you paste WikiText markup from source editing into the Visual Editor, it will convert the text for you, rather than see it as plain text - super useful when copying between pages.

Other essential page formatting is more complicated:

Tables can be inserted easily enough using the Insert button and selecting Table. Click the button and a table is inserted into the page.

You can use the buttons to add columns and rows. You can also edit the properties of the table with the Properties button, for example, to get rid of the caption if you don't want it.

Editing the contents of the table is directly in the cells themselves - much easier.

Warning: Unfortunately, you can't (yet) add searchable tables through the visual editor. Worse, the visual editor may remove your searchable tables code when saving the page, so a bit of a downside.

Images are covered in a following section.

Standards

To maintain a fairly standard set of documentation, use the following guidelines:

Buttons should be in Bold.
Tabs and menu options should be in italics.
Keyboard shortcuts or code should be in Code or Preformatted format.
Leave two lines between sections.
Use templates - see Templates section below.
Reuse documentation where possible - if there is already a page describing how to use or do something, include that page - see Transcluding below.

Images

Images must be uploaded to be used in pages, which is a bit of a pain, but really aids in reusability of images.

Warning: Bear in mind that, with either Source or Visual editing, you can't trim or edit the image when it's uploaded, so make sure what you're uploading is what you want to see in the final document.

Warning: Be very wary of using scalable graphics formats, such as SVG. Although they look fine in the web pages, the images do not render in the PDF print at this time.

When source editing:

These images need to be saved first.

Easiest is to use an image editing application such as MS Paint, which makes this fast and easily editable.

Take a screenshot of your screen (CTRL-PrtSc) or the active window (ALT-PrtSc).
Paste into Paint.
Crop and Save to a local file - use PNG format by preference.

Alternatively, use the Windows Snip and Sketch tool to do the same.

Clicking the Image button will show a dialogue to enter:

Filename: enter a filename for an image that has been uploaded, or enter a new name. Keep it relevant, like "VEhub_Login.PNG"
Caption: optional
Alternative text: optional
Size: optional, but any image that you ware uploading that is greater than 1000px wide should be reduced to that or 800px, to make them fit in the PDF when produced.
Align: Left, Center, Right or None.
Format: Choose None.

You have an Upload button here, so you can upload the image you have already saved to your PC.

When visual editing:

You have lots of options to create a new image.

You can take a screenshot of a screen or window as above or copy an image from a document or filesystem, then just paste (CTRL-V) in the editor - the Image dialogue will appear, showing a thumbnail, allowing you to name the image, then edit any properties. Steps:
- Paste the image - the image popup will appear.
- The image will initially be named "image.png" - that's OK, as we will change it in a minute - Check "This is my own work" and then click Upload.
- Enter a name - make sure that this is unique and relevant, , like "VEhub_Login.png" or "Tesla Order Search 1.png".
- Enter a description - the dialogue forces you to enter a description - you could just copy in the filename, or (preferably) enter a description, maybe also a unique ID like the screen name.
- Click Save - the properties box will be displayed - see below..
You can drag and drop a local image from your PC straight to the window. When you drop it, the Image dialogue will appear, showing a thumbnail, allowing you to name the image (which will default to the name of the file being uploaded). From that point, it's similar to the above process, of uploading, naming, saving and editing properties.
You can choose images you have recently uploaded by selecting the Insert button on the toolbar and selecting Images and Media. You can then select the image from the Search tab, select it, click Use this image and then amend the properties. This is super-useful when combined with batch uploading of images (below).
You can choose to re-use images that have already been uploaded onto the Assist by anyone - select the Insert button on the toolbar and selecting Images and Media. You can then search for images by their name from the Search tab. When you find an appropriate image, you can select it, click Use this image and then amend the properties.
You can directly upload a saved image by selecting the Insert button on the toolbar and selecting Images and Media. You can then select the image from the Search tab and then amend the properties.

The properties you can edit are:

Caption: optional
Alternative text: optional
Position: Left, Center, Right or None. Choose Center or None. If will turn itself off if you select a Basic image.
Image Type: Choose Basic.
Image Size: optional, but any image that you ware uploading that is greater than 1000px wide should be reduced to that or 800px, to make them fit in the PDF when produced.

Then you can insert the image.

For updating an image that already exists, however, your options are more limited. It's important that we update images, rather than upload new ones. If you attempt to paste in an image and call it the same thing as something that already exists, Visual Editor will throw an error.

To update the image, you have to save as a picture file first:

From a Word document, right-click, Save as Picture, give it a name and save.
From printscreen, paste into your paint application and save as PNG.
From Snip and Sketch, save as PNG.

You can then:

click on the image link and upload a new version from the upload page.
click Upload File from the Wiki Tools toolbar on the left and upload a new copy.
batch upload the file - see below for details.

Regardless of which editor you are are using, you also have the ability to batch upload images. So, if you have created all the images you need and named them appropriately, you can upload those images using the Special page "Upload Multiple Files". From there, you can drag and drop or multi-select all of your images into the system, then use them in your page.

Save your images to local files in a unique and reasonable filename - if it's reusable for other things, make them relevant, as above.
- From a Word document, right-click, Save as Picture, give it a name and save.
- From printscreen, paste into your paint application and save as PNG.
- From Snip and Sketch, save as PNG.
Go to the Assist Special pages
Select Upload Multiple Files
Enter a description if you want - it's optional, but can be useful. For example, if uploading a load of images relating to a Tesla Support document, you might enter "Tesla Support Images". But you can also leave this blank - that's perfectly fine.
Either
- Select all your images in a Windows explorer and drag and drop to the appropriate place on the page
- Click the button, multi-select from the popup explorer and confirm.
The files you selected will be shown in a list on the page.
As they are uploaded, they will change colour to show whether they uploaded successfully or not
- If they turn green, all good.
- If they turn red, they didn't upload - check the error reason and correct.
Warning: Uploading a file that already exists will create a new version of that file - you should check where this image has been used before and make sure that the image you have uploaded is appropriate to all pages that use it.

Templates

Where possible, the templates created for you should be used when creating and within the document.

We use Templates when we want a consistent look to certain things, from simple things like a notation, to more complicated things like a full document.

You can add templates quite easily:

Source Editing:
- Just type in double-curly bracket notation like {{Warning}}
- Or Click the Template button, type the name or part of the name of the template you want to use, for example "War" then select it and Insert.
Visual Editing: click the Insert toolbar option, then Template. Type the name or part of the name of the template you want to use, for example "War" then select it and Insert.

Some more complicated templates have parameters that can be passed to them. In the example above, "Warning" can accept a single parameter of the warning text itself. It's optional in this case, but some really complicated templates (like Doc Title) have lots that are required to be entered - you use it like this:

Source Editing:
- With positional parameters, just vertical bar delimit the parameters like so: {{Warning|My warning text}}
- Some templates support named parameters, like so:

{{Xref
|Type=Example
|Num=1
|Text=The text describing the cross-reference
}}

- Or Click the Template button, type the name or part of the name of the template you want to use, for example "War" then select it. You can then enter the parameters and Insert.
Visual Editing: click the Insert toolbar option, then Template. Type the name or part of the name of the template you want to use, for example "War" then select it. You can then enter the parameters and Insert.

Some simple templates:

Note - This provides a note graphic Note: like so
Warning - This provides a warning graphic Warning: like so
Hint - this provides a hint note Hint: Like so.
Xref - this provides a cross-reference in a standard format. Use it like so: {{Xref|Type=Image|Num=1|Text=An image of something}}
Incomplete - this adds a warning that the document is incomplete, and adds the document to an Incomplete category, so it can be easily found and completed. Use it like so: {{Incomplete}}
Generic glossaries have been provided for the CALIDUS products -
- You will find them in the Glossaries category.
- These can be added to and amended if required by clicking on the glossary template in the editing screen.
- Note: All Glossaries are now maintained in this Assist, the Calidus HUB. That means that you can add them to your pages or documents or refer to them, but they are all referred to as part of the "obs" namespace. This is a special bit of functionality known as Interwiki, and is dealt with below.
Test Plan templates are available to construct test plan cycles - see the Functional Specification template for details on how these work.
A Comment template has been added to identify comments added to a reviewed document easily

like so
—User:Anw, 31/1/2012 16:33:36

Some complicated templates:

Doc Title - creates a document title page.
Doc Appendix - creates a document appendix page.

Some full document templates: Document templates have been produced for the following document types:

Requirements
Estimates
Functional Specifications
Small Change Requests
Test Plans
ERs
Patches

and many more.

Full document templates can also be accessed through the Help:CreateNewPage page.

The links on that page will help you generate a new document or page.

Enter the title of the page or document you are creating in the right entry box for the document that you want to create.
Click the button.

The system will copy everything required in the template into a brand new page created for you, so that you can complete editing it.

There are pretty extensive guides in the Assist category on creating pages (specifically release notes) from Templates - it is advised that you look there for more information.

Transcluding

Tranclusion is all about re-using pages that you have already created. We can (and should) do this, as "edit once, edit everywhere" applies, meaning that the pages are updated in every other page or category that uses them, massively reducing the amount of effort required to get changes into the right places.

Say for example, you have documented the Resource Allocation process in a page called "Allocate Resources". That screen is called from the Planning Screen and from the Waterfall screen, which are also documented. You want to describe resource allocation in the documentation of those pages, but you don't want to have to type it all in again, or have to keep updating multiple pages because a small change has happened to that Resource Allocation screen. You could just add it as a like , for example, "see Allocate Resources for more information", but you really want a complete document here. Transclusion helps here.

In the Planning page, you add a Header for "Allocating Resources"

Source Editing: == Allocating Resources ==
Visual Editing: Choose the Heading 2 format from the toolbar and type "Allocating Resources".

Then we can transclude the page:

Source Editing: {{:Allocating Resources}}
Visual Editing: On a new line, click the Insert toolbar option, then Template. Type a colon, followed by the page e.g. :Allocating Resources, then select it and Insert.

That's it - the page will be included at that point in your Planning page. Whenever Allocating Resources changes, the planning page will also update.

You can see wherever a page in included or linked to in any other pages really easily. Click "What links here" in the "More" toolbox section. That will show you a list of all:

Transclusions - directly used in a page.
Redirects - stub pages that immediately redirect to this page
Links - just a link has been added.

That way, when you edit a page, if this edit fundamentally affects a document that is produced from those linked pages, you can edit those if necessary, perhaps to increment a version or modified date, if these pages are producing a PDF book.

Interwiki

As you know, the Assist systems are based on MediaWiki, then engine that powers Wikimedia.

Each product has its own instance of this, so we have Assist (wiki) instances of (amongst others):

OBS - Calidus HUB
MTS - Calidus TMS
WCS - Calidus WCS
WMS - Calidus WMS 3pl
Portal - Calidus Portal (all types)
MCS - Calidus MCS

In the interests of reducing duplication and possible out of date guides existing within other pages, each of these Assists can use pages out of the other Assists by using a defined interwiki reference.

What that means is you can link to or transclude ANY page from any other Assist, like you would for any page on your Assist.

So, the interwiki shortcuts are:

Calidus HUB - "obs"
Calidus TMS - "ctms"
Calidus WCS - "cwcs"
Calidus WMS 3pl - "cwms"
Calidus Portal - "cportal"
Calidus MCS - "cmcs"

Essentially, you use the Interwiki prefix before the page or template you want to use.

To use a template from another wiki, the syntax is {{iw:TemplateName}}.
To link to a page from another wiki, the syntax is [[iw:PageName]].
To transclude a page from another wiki, the syntax is {{:iw:PageName}}.
To use an interwiki link for a DocLink, the syntax is {{DocLink|:iw:PageName}}.

As mentioned above, Glossaries for all systems are maintained within the Calidus HUB Assist. The page exists in the local wiki, but it transcludes the Calidus HUB version. So, you can continue to use the template {{WMS Glossary}} as normal. But you could also use {{obs:WMS Glossary}} instead and get the same result.

Best use cases for Interwiki functionality are:

Repetitively-maintained and used data, for example Glossaries.
Technical guides linking to customer-facing guides, for example on this wiki CTMS Paragon Interface, where the customer-facing guide maintained in the CTMS Assist is both linked to and transcluded.
Product-specific pages linking to technical specs, for example, in WMS, you would find PoD Guide, which links to the Port of Dover SDD on this Assist SDD 350229 Port of Dover Solution Design as a DocLink to download the PDF i.e. {{DocLink|obs:SDD 350229 Port of Dover Solution Design}}

In this way, we further promote the "write once, write everywhere" mentality and reduce effort, which providing a more connected, more up to date documentation set to our customers.

Saving your Changes

Each change you make, however small, is included in the document's history. To ensure that these comments are not included, you should mark the change as minor when saving your changes. However, this should not be marked as minor if the edit fundamentally changes the document.

Comments should be added whenever saving edits. If you have edited a section directly, rather than the whole document, a comment will already be entered for you. You can leave this there, replace with a new comment or add your comment after this one.

Your comments should reflect the changes. It's good practice to reference any call numbers or system versions associated to the change of you know them. Avoid client names if you can - remember this is standard documentation! For example, for a SalesForce or DevOps change 123465 for customer ABC Travel, adding a new Customer Ref field to a screen, consider entering your comment as follows:

Added new Customer Ref field (123456)

As documentation should always be updated when software patches or releases are made available or released to a customer system, then consider using the ER/patch/release number in the comment, for example:

ER CTMS 047-101 - Added (some functionality) to the screen

When a document is going to be changed to a new version, you should change the version and date within the document, and add the version number to the start of the comment. For example:

v0.02 - Draft issue for review
v1.00 - Ready for Issue.

How this works is slightly different for each editor.

For Source Editing:

Enter a summary comment.
Check whether this is a Minor edit.
Optionally you can Watch this page - if anyone edits it in the future, you'll get an email. You can manage your watchlist from user preferences accessed from your user name.

Once you have selected, you can do the following:

Save changes - if you haven't entered a summary comment you will be reminded, or the changes will just be saved.
Show preview - as you are probably using realtime previews, probably not required. If you do use it, the changes will be shown on the top of the page, but remember your changes have not yet been saved - use the Save changes button as above to commit them.
Show changes - show all changes in text differences showing each line changed, added or modified in a list. Remember your changes have not yet been saved - use the Save changes button as above to commit them.

From Visual Editing:

Click Save Changes
You will be shown a popup - enter your summary here.
Check whether this is a Minor edit.
Optionally you can Watch this page - if anyone edits it in the future, you'll get an email. You can manage your watchlist from user preferences accessed from your user name.

You then have options.

Save changes - if you haven't entered a summary comment you will be reminded, or the changes will just be saved.
Review your changes - show all changes in differences. The changes will be shown in Visual ode with colour highlighting - you can switch to the text differences above as well if that suits you better. Remember your changes have not yet been saved - use the Save changes button as above to commit them.

Some Final Notes

Note:

When creating a new document, you should ensure that the Category tags are added relevant to that document type and client. This allows for easy searching of documents. See the following section on Categories.
A document should be checked that it exports to PDF correctly - in most cases, documents will export with no issues. However, it has been known that a document does not correctly format into PDF. If this is the case, the document should be referred to the Assist maintainer for checking. Documents can be exported to PDF from the toolbar.

Issuing Documents to a Client

Documents should be issued in PDF form.
The document title should follow the standard document template, with a version number, so:
- EST 123456 CUSTREF Title v1.0.pdf
If you use the standard document template with the Doc_Title title page and you specify a version, when you download the PDF, the document will be appended with the version number automatically.
Whilst the Assist system is being adopted, these documents should be held in the standard development or project document folder - please consult your project or product documentation for details.

Appendix A: Document History

A.1 References

Ref No	Document Title & ID	Version	Date
1
2
3

A.2 Document History

Version	Date	Status	Reason	By
0.1	25/02/2020	Issue	Initial Version	ANW

A.3 Authorised By

Julie Scott	OBS Manager	_____________________________
Tony Walker	OBS Consultant	_____________________________

Anonymous

Search

UG 352360 CALIDUS Assist User Guide

Creating articles for inclusion in a PDF Book

Single Page

Creation of a Book

Production of the PDF

Setup Requirements

Creating new documents from templates

Creating a new Wiki installation

Initial Setup

Configuration

Site config

E-mail, e-mail notification and authentication setup

Database config

MySQL-specific options

Further Configuration

Creating the basic content

Creating Users

Upgrading the version of an existing Wiki installation

Software Required

Prior to Upgrade

Upgrade

Editing a document

General

Document Editing

Source Editing

Visual Editing

Standards

Images

Templates

Transcluding

Interwiki

Categories

Saving your Changes

Some Final Notes

Issuing Documents to a Client

Appendix A: Document History

Navigation

Wiki tools

Page tools

Categories