Sandbox:Piffpoof4

= Linking Scripts and FreeCAD files to Wiki Pages=

Background
FreeCAD uses a Wiki system to provide user documentation. The need exists in the documentation to provide both Python script files and FreeCAD documents (which are binary files). This page describes how those two types of documents can be linked from the WIki.

Introduction
A Gist is a concept within the git systems of a short piece of code, say for an example. It is different from a git repository as the git repository most often has multiple files. To further confuse the difference, the Gist has a full version control history as does a proper git repository. Also it turns out that a gist can hold more than one file, further blurring the distinction between gist and git repository. The FreeCAD Wiki uses the gist concept to hold examples that are either Python script of FreeCAD document files (i.e. ,FCStd files).

Creating an Account for 'git'
A git account is required to hold the files which will be attached to the WIki pages, if you need to create a git account then Click Here

Linking to Python Script files and FreeCAD binary Files from Wiki
The following process is done in two inter-related parts: To differentiate the two places that actions are performed, this document uses the following convention: There are 2 conventions used here for describing git components:
 * one part is on the webpage of the git repository,
 * the other part is on the computer at command line prompt using the git software.
 * steps with letters (e.g. 'A', 'B' etc.) are steps on made on the website,
 * steps with numbers (e.g. '1', '2' etc.) are made on your computer using the git software.
 * the git will be created with a user assigned name (e.g. 'myNewGit') but the software will refer to it by a long alphanumeric tag, this page description uses '' to represent the git tag, in real life the git tag could be something like 'c841d68e15ac152d59c6'.
 * as the git repositories are based on user IDs for signing in, the path name to a gist will have the user name as part of the path, this page description uses '' to represent the user name, in real life the git tag could be something like 'fido'

Together the git tag and user ID would give a path like which this page would represent as
 * https://gist.github.com/fido/c841d68e15ac152d59c6
 * https://gist.github.com/ /

Creating a 'Gist'
(performed on the web page)

It seems that a new 'Gist' can only be created using the webpages of github.com. Consequently we will create a file in the new Gist so it can be created.

A	after signing in you should be on the page: https://gist.github.com/ B	click on "+" to create new gist - you can not create an empty gist, so the first file must be 	added in the same operation that creates the gist C	give the gist a name D	enter a name for the first file - this first file is where the Gist will take it's name from, it doesn't serve any other purpose, but if it is deleted then the name of the Gist will change to the second file loaded, the will not change so no links will be	affected, only the name within GitHub will change E	enter some contents for the first file - perhaps some descriptive text as this file must remain to 	maintain a constant name for the Gist F	click "Create public Gist" G	you will end up on page https://gist.github.com/ / H	the alphanumeric after the user name is the tag of the gist I	make a note of the gist tag as you will need it in later steps

You now have a new gist with a single file in it.

Note : make note of the git tag as you will need it multiple times in later steps - it will be of the form 'c841d68e15ac152d59c6'

Cloning a 'Gist' & Adding a Binary File
(performed at the command line prompt using git software)

1	go to a directory where you are going to work with the git code 2	git clone https://gist.github.com/ / .git - a directory named the same as the will appear (e.g. 'c841d68e15ac152d59c6') and it will have the initial file you put into the git repository 3	cd (e.g. cd c841d68e15ac152d59c6) 4	now move a binary file into the clone directory, by either: cp /home//someBinaryFile.bin. or use your file browser to move a file in 	or save a file from FreeCAD into the directory 5	git add -A 6	git commit -m "commit message" 7	git push

You have now added a binary file to your newly created gist which will now have 2 files.

In a similar fashion you could add any type of file, binary or text, to the Gist.

Update Gist Display on Web Page
(performed on the web page)

J	sign into github - you should be on the page https://github.com/ K	click on the "Gist" button at the top of the page - you should now be on the page https://gist.github.com/ - your Gists should be listed L	click on the button "Your Gists" in the upper right corner - you should be on the page https://gist.github.com/ - there should be a list of your gists M	for the gist you just created, there is a button "<>" followed by 	a digit and the word "files", click on the "<>" - you should be on the page https://gist.github.com/ /, where it lists two files: - the file you added initially to create the gist - the binary file you added second

You will now choose one of the two following steps, depending on whether you want to link to a text file such as a Python Script file, or whether you want to link to a binary file such as a FreeCAD .FCStd document.

Copy Link for a Binary File
(performed on the web page)

If you are placing a link to a binary file on your Wiki page, then perform the following step:

N1	for the binary file there will be a link "View Raw ->", right-click on this link and copy the link - jump to step O

Copy Link for a Script File
(performed on the web page)

If you are placing a link to a text or script file on your Wiki page, then perform the following step:

N2	for the script file there will be a link "Raw" at the right end of the box surrounding the name of the script file, click on this link N3	the page will now be a listing of the script file, copy the URL from the ORL field at the top of the browser - jump to step O

Create Wiki Links
(performed on the web page)

O	In your Wiki page, enter a line of the form: [XXX some description for the link] where XXX is the URL you copied in step N 	It will be of the form: https://gist.github.com/ / /raw/xxxxx/fileName.FCStd P	remove the 'xxxxx' so you have a file specification of the form: https://gist.github.com/ / /raw/fileName.FCStd Q	substitute this file specification for the XXX in the Wiki line of step O, 	so you end up with a line in your Wiki of the form: [ https://gist.github.com/ / /raw/fileName.FCStd a link description] R	this link is now directed from the Wiki page to 	the latest version of your binary file at the github

You now have a Wiki page where both the links can be right-clicked and the Save File As option selected. The user can then direct the downloading of either a Python script file or a Python binary file (*.FCStd).

Examples

 * a Python Script file


 * a binaryFreeCAD FCStd document

Right-Click and select the option "Save File As" to save either of the above files. The first one is a Python file with indentation complete, the second one is a FCStd document to be opened with FreeCAD.