Mallard and GIT

Mallard is a tool for writing documentation on Internet based on XML, that shows the text in a modern and fresh way to facilitate users reading, specially for newbies who wants to learn and explore a particular software or whenever any user require help in using specific module, in specific software. This is normally call “the topic -oriented format”, so that allows users to optimize time in reading and only if they want to deep in information, they just have to click to read more stuff related on. I don’t need to convince anyone about using Mallard, just compare old fashion pages like “Guide to the W3C Specification” vs pages developed with Mallard, like the page of Gnome ” Empathy Internet Messenger “.
*  Extensibility, that permits updating the document by different adding documentation from different people without modifying the original sources.* Easy to use is other important factor of this tool. Learning Mallard could take a couple of hours, or less if you are so familiar with HTML o XML. (See:Ten minutes tour)* Testing is more than easy… just run the command yelp on terminal with the directory the files are into browse the documents inmediately. For example if we put the index.page in /home/ yulys/mallard, type #yelp /home/yulys/mallardIn this article I’m going to show you how to use Mallard. First, you need to abstract the topic in order to present a general idea of it, then be more specific in details deeply later. For example, in this case, I want to introduce the git project and I’m going to do this trough presenting 3 general aspects like introducing GIT, installing GIT and coding GIT… Let’s practice🙂Step 1.-Create a directory called mallard in /home/yulys, here we are going to host all the files later

[yulys@yulys ~]$ mkdir mallard

**If you got this image while you are editing, just change the mode of the file: chmod a+x

Step 2.-

Write the front page in any text editor and save as an “index.page”, this file had been created inside the mallard directory

[root@yulys mallard]# gedit index.page

index.page


<page xmlns=”http://projectmallard.org/1.0/&#8221;
type=”guide”
id=”index”>
<title>GIT project</title>
<media type=”image” src=”Git.png”/>
<media type=”video” src=”LinusTorvaldsonGit.ogv”/>

<p>Also you can find the video here: http://www.youtube.com/watch?v=4XpnKHJAok8 </p></page>


* XML data is structured like a tree. The root element being with <page>… </page>, we set up type=”guide”  as its purpose is to help users navigate to other content,  id=”index” identifier of  principal page <title>… </ title> , children of “page” and indicates a title page. <media type =”image” scr= …> puts Git image  and <media type = “video” src=… > insert video in the index.page. The image and video file have to be inside the mallard directory.

Step 3.-

Create three files to get the principal ideas of Git: introducing Git, installing Git, coding Git inside the mallard directory. They are part of the index.page, so we need to specify it:

[root@yulys mallard]# gedit introGit.page

introGit.page


<page xmlns=”http://projectmallard.org/1.0/&#8221;
type=”topic”
id=”introGit.page”>
<info>
<link type=”guide” xref=”index”/>
</info>
<title>Introduction to Git</title>
<p>
Git is the source code control management system created by Linus Trovals in 2005, most written in C that can manage projects of different sizes with speed and efficiency.  This tool offers better performance than others version control systems like Subversion(SVN), Mercurial, CVS, Perforce and Visual SourceSafe.
</p>
<p>
The document can be distributed to everyone (is not central central process) and each clone of Git present the whole history from their origins,  that allows the full revision tracking and handle it independently as a full-fledged repository.
</p>
<p>
Finally, Git does not depend on network access or a central server. This is a feature that is not support by any other control management system.
</p>
<steps>
<item><p>GNOME projects and KDE projects use Git</p></item>

<item><p> Perl projects and Ruby projects also use Git</p></item>

<item><p> Android, Debian and and many more projects use Git too</p></item>

</steps>
<p>   * Imagine having 5 users or developers working on the same project: managing 5 files would mean 20 more files to deal with. Most projects will have many, many files and even more developers– it’s enough using Google Docs if you are a final user. In the case you are developer or programmer it wont be so useful because you need more information about the code log, etc.
</p>
</page>


* To specify that introGIT is a topic of the guide page, we put in type=”topic”  as its purpose is showing new content that belongs to the index.page. The relationship between these two pages are showing in <info>… </info> trough xref command. <p>… </p> in this case, like HTML introduce a paragraph. <step>… </step> creates a list of steps to follow, each one can contain one or more paragraphs or other block content.

 
 
 
 
 

 [root@yulys mallard]# gedit installGit.page

installGit.page


<page xmlns=”http://projectmallard.org/1.0/&#8221;
type=”topic”
id=”installGit”>
<info>
<link type=”guide” xref=”index”/>
</info>
<title>Installing Git</title>
<table shade=”rows”>
<tr>
<td><p>Windows</p></td>
<td><p>http://code.google.com/p/msysgit/downloads/detail?name=Git-1.7.4-preview20110204.exe</p></td>
</tr>
<tr>
<td><p>Linux</p></td> <td><p>Package git-1.7.5.1.tar.bz2 → http://git-scm.com/</p></td>
</tr>
<tr>
<td><p>MAC OSX</p></td> <td><p>Packages are → http://code.google.com/p/git-osx-installer/downloads/list?can=3</p></td>
</tr>
</table>
</page>


* To specify that installGit is a topic of the guide page, we put in type=”topic”  as its purpose is showing new content that belongs to the index.page. The relationship between these two pages are showing in <info>… </info> trough xref command. <table shade=”rows”> present a table with shadows rows  <tr> for rows and <td> for columns.


 
 
 
 
 
 
[root@yulys mallard]# gedit codeGIT.page

codeGit.page


<page xmlns=”http://projectmallard.org/1.0/&#8221;
type=”topic”
id=”codeGit.page”>
<info>
<link type=”guide” xref=”index”/>
</info>
<title>Coding with Git</title>
<p>To check if you have installed Git, just type the command:
<code>git –version</code>and you will see in this case 1.7.4</p>
<p>To start with Git, make sure where you are going to save the files. Here we are on mallard directory and we are going to create testdir directory
<code>mkdir testdir </code>that creates “testdir” directory</p>
<p>To start with Git, make sure where you are going to save the files
<code> cd testdir </code>to get into testdir</p>
<p>Initializing git:
<code>git init</code> This message confirms the operation.“Initialized empty Git repository in /home/yulys/mallard/.git/” … if you don’t remember, just type git help and choice “init”</p>
<p>To add files on mallard directory, for example “hello.txt”, you have to create the file inside mallard directory first  <code> echo “hola”>mundo.txt</code> This append hola in mundo.txt</p>
<p>Then you have to tell git that hello.txt is going to be tracked it:
<code>git add mundo.txt</code>… mundo.txt is the file being tracked </p>
<p>To add a commit <code>git commit -a -m “saludo inicial”</code> my comment was: “saludo inicial”</p>
<p>To see the differences of the last version and the uncommitted file you are working on:
<code>git diff</code>with diff you see the changes clearly</p>
<p>Finally, you can see all the commits the file suffers being manipulated by many people. <code>git log</code>The log command will give you the commit hash (the unique ID of your commit), the author of the commit, and the date/time it was committed.</p>
</page>


* To specify that codeGit is a topic of the guide page, we put in type=”topic”  as its purpose is showing new content that belongs to the index.page. The relationship between these two pages are showing in <info>… </info> trough xref command. <code>… </code> let us shine the commands in the document. <p>… </p> to brace paragraphs


Web sources:
http://camille.begnis.org/publications/XML/xml_overview/more.html
http://projectmallard.org/
http://learn.github.com/p/intro.html
http://git-scm.com/
http://sixrevisions.com/web-development/introductory-guide-to-git-version-control-system/

About Julita Inca

Ingeniero de Sistemas UNAC, Magíster en Ciencias de la Computación PUCP, OPW GNOME 2011, Miembro de la GNOME Foundation desde el 2012, Embajadora Fedora Perú desde el 2012, ganadora del scholarship of the Linux Foundation 2012, experiencia como Admin Linux en GMD y Especialista IT en IBM, con certificaciones RHCE, RHCSA, AIX 6.1, AIX 7 Administrator e ITILv3. Experiencia académica en universidades como PUCP, USIL y UNI. HPC researcher, a simple mortal, like you!
This entry was posted in GNOME and tagged , , , , , , , . Bookmark the permalink.

11 Responses to Mallard and GIT

  1. [yulys@yulys ~]$ su mkdir mallard

    I’m trying to understand why ‘su’ ?

    • Julita Inca says:

      su is like sudo, to get superuser permission… be careful with this… like Diego says, it could be dangerous for your health… I going to try again and I’ll led you know what happens

      • I mean why is it there. You shouldn’t have to edit your own files as root. If you find you have to, check the file permissions and file ownership (ls -l), you can then change these with the commands chmod and chown.

      • Julita Inca says:

        That’s a good practice!, I am going to correct it… I did the easiest and dangerous way =( I wont do it again in public.

  2. diego says:

    You don’t need to use ‘su’ and become root. Working as the “yulys” (regular) user is enough.
    Working as root can be dangerous for your health.

  3. Robin says:

    Please, please don’t write GIT, it’s not an acronym. It’s just called Git (as a normal name).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s