Sandbox:Piffpoof4

From FreeCAD Documentation
Jump to: navigation, search

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:

  • 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.

To differentiate the two places that actions are performed, this document uses the following convention:

  • 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.

There are 2 conventions used here for describing git components:

  • 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 'gitTag' 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 'userName' 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

  • https://gist.github.com/fido/c841d68e15ac152d59c6

which this page would represent as

  • https://gist.github.com/userName/gitTag

Creating a 'Gist'

(performed on the web page)

It seems that a new 'Gist' can only be created using the webpages of github.com. Also it seems that a file must be created as part of creating a new Gist, consequently we will create a new file in the new Gist as part of the creation process.

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 description
D	enter a name for the first file
	- this first file is necessary for the Gist to be created,
	you can edit or even delete the file later
E	enter some contents for the first file
F	click "Create public Gist"
G	you will end up on page
	https://gist.github.com/userName/gitTag
H	the alphanumeric after the user name is the tag of the gist
I	make a note of the gitTag 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 gitTag 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/userName/gitTag.git
	- a directory named the same as the gitTag will appear
	(e.g. 'c841d68e15ac152d59c6')
	and it will have the initial file you put into the git repository
3	cd gitTag
	(e.g. cd c841d68e15ac152d59c6)
4	now move a binary file into the clone directory, by either:
	cp /home/userName/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/userName
	- 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/userName/gitTag,
	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.

Note: the display of the GitHub.com software is not consistent, for a given Gist, it will usually list the file most recently added. This can be a bit confusing as there isn't a user assigned name for the Gist but only the system generated gitTag. Sometimes you must click on the file listed, the most recently added file, in order to access the file you want.

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/userName/gitTag/raw/xxxxx/fileName.FCStd
P	remove the 'xxxxx' so you have a file specification of the form:
	https://gist.github.com/userName/gitTag/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/userName/gitTag/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

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.