Ticket #423: quickstart.txt

How it will be:
---------------

Lumiera website is meant to live through uWiki 
(see link:http://git.pipapo.org/uWiki.html[] )
uWiki is still in development, so for now, the website is built from AsciiDoc and git.

How it is now:
--------------

Website pages come from TXT files, written with AsciiDoc markup, that are 
committed to the Lumiera git repository and converted to HTML with 
an AsciiDoc script. The pages have two external CSS (stylesheets),
 one for the layout and one for styling the Asciidoc markup.


Editing a Webpage
~~~~~~~~~~~~~~~~~

 1. Get the site from git repository(repo)
        a. Use git gui (or cola) and clone the repository from 
           link:http://git.lumiera/org/git/website-staging[]  (master branch)
        b. Of course one can use the command line, I presume you already know git. 
           repo: link:http://git.lumiera/org/git/website-staging[]

 2. Edit the txt(s) by following the directions in "Write Asciidoc Now!" below

 3. View the effect of your edits:
        a. Locally by running build_website.sh in your git repo
        b. Remove generated html files by searching the repo for ".html" and 
           deleting all (BJMR's quick'n'dirty method)

 4. Use git (or gui) to commit locally.
        a. Please summarize what/why on line 1 of the commit note 
        b. On line 3 detail what you've done.
        c. These commit notes are the way we understand the work you've done

 5. Check for other's edits & push 
        a. You will need a git account \~usr@git.lumiera.org to push to the server
        b. Use a fetch or pull command from the master repo (on git.lumiera.org 
           server)
        b. If there is nothing new from the server (repo up-to-date) See "d"
        d. If changes are made check what files are different from the server: 
           merge, see "d"
...If they conflict with someone else's edits either carefully merge and check the results
...or ask someone (like the author of the edits) on irc/email  irc.freenode.net #lumiera
        d. Push your edits to the server (origin, master branch)

Editing Pages in Asciidoc
~~~~~~~~~~~~~~~~~~~~~~~~~~

All the website pages are built with txt files using Asciidoc markup. 
If you've ever used a wiki markup, Asciidoc is similar.

An AsciiDoc cheatsheet: link:http://powerman.name/doc/asciidoc[]
The cheatsheet is a great reference to have open while editing and shows many 
more advanced features than covered here.

To know a lot about AsciiDoc markup see AsciiDoc website at:
link:http://www.methods.co.nz/asciidoc/[]

I use gedit text editor, bundled with GNOME. I also use:
 link:https://launchpad.net/asciidoc-gtk-highlight[Asciidoc Syntax Highlighter] 
to add highlighting like one could with html, script or code.

But here is a quick overview of our document style...

CAUTION: If any features are causing problems/not functioning as described, 
check your code, then let us know!

Headers/Titles & Lists
^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------------
Very top title of the page
===========================
^the '=' signs make it the page header
----------------------------------------

Make sure for titles/headers the underlining is the whole length of the content,
otherwise it may not display correctly. 
One trick is to add an extra mark past the content above. 
Also, be very careful to leave a line return above and below titles and headers.

Because I spend a lot of time looking at the asciidoc files,
 I like the "underline" style of titles/headers:

Header/Title size 1
--------------------
^For major sections of the document, in some pages there may only be 1

Header/Title size 2
~~~~~~~~~~~~~~~~~~~~
^For sub-sections, I use these alot because they aren't huge on screen, 
 but render with a line below in html

Header/Title size 1
^^^^^^^^^^^^^^^^^^^^
^Break up steps or details with this, in html has no underline/hr

Header/Title size 1
++++++++++++++++++++
^Haven't used one yet :)

 * Make simple
 * Lists
 * With asterisk '*'

. Make Complicated
.. Lists
... with periods '.'
. The number of periods 
... determine
.. how far indented 
. the
..... text
.. will be

Links
^^^^^^

To add a 'link': use 'link:<~url>[<Visible link Text>]'

=> replace: <...> and leave the brackets '[]' at the end,
 even if you don't fill them.

link:{l}/index.html[Home Page]

For troubleshooting and archival purposes, we are having the full (absolute) url
 of links and images added with a simple command. As the build script runs, 
it uses an 'attribute tag' in layout1.conf to replace:
 \{l} with \http://staging.lumiera.org
When the site moves from staging.lumiera.org to the main url, 
the 'l' attribute will be modified accordingly.

TIP: In your local git repo duplicate layout1.conf, and chage the value of 'l'

--------------------------------------------------------------------------------
l=http://staging.lumiera.org   to:
l=/foo/...yourgitrepo

DO NOT add a trailing / to the location, 
these are written into the actual link in the Asciidoc page
--------------------------------------------------------------------------------

Images
^^^^^^^
Similar to links:

'image:<~url.img[<Alt text>]'
image:{l}/images/lao.png[<penguin>]
You can have a thumbnail image link to the full-size with:
image:<~url1.img>["<Alt text>", width=<###>, link="<~url1.img>]

Design and Style Editing
~~~~~~~~~~~~~~~~~~~~~~~~~

The style breaks down as this:

Layout of the html-page elements are in link:/layout1.css[] & 
link:/layout1.conf[], which are used by the build_website.sh.

At present, there should be little reason to edit the html in the '.conf' file, 
as almost all layout and styling can be done through the '.css'.

The CSS files are decently documented with ' /* -- comments -- */ ' to explain 
the structure and hopefully function of the elements. Make sure to look over the
html and css relationship and get some understanding of how it works. First see 
the header in link:/layout1.conf to understand the configuration of 
site elements, and then move on from there.

Styling for how Asciidoc markup appears in the #layout-content area of the page 
is in link:/xhtml11.css[]
Use this to change fonts & colors, link decoration, spacing, etc.

* To edit the style of the credits page edit link:/project/credits.css[] 
and link:/project/credits.conf[]


What happens when you push to the server
-----------------------------------------

Push the changes to git.
That will activate 'post-receive', a git hook that automatically checks 
the files out and run 'build-website.sh', a script that converts 
the AsciiDoc TXT sources to HTML webpages. 

The full path of the 'post-receive' git hook is:
/var/www-staging/.git/hooks/post-receive

The full path of the 'build-website.sh' script is:
/var/www-staging/build_website.sh  +
or locally: .../~sitegitrepo/build_website.sh

The task of the 'build-website.sh' script is to run the asciidoc command 
to create not just HTML pages but real webpages pointing to external CSS. 
This script contains the list of TXT files to be converted to HTML webpages.