From 04d3b1d9048ba306570031371e028cfd831dbd24 Mon Sep 17 00:00:00 2001 From: Alexandre Dupas Date: Tue, 10 Mar 2009 20:44:26 +0100 Subject: [PATCH] Add documentation/website into the project --- doc/bugs.mdwn | 5 ++ doc/bugs/done.mdwn | 3 + doc/bugs/needs_more_bugs.mdwn | 2 + doc/bugs/song_request.mdwn | 3 + doc/contact.mdwn | 5 ++ doc/doc.mdwn | 5 ++ doc/doc/faq.mdwn | 23 +++++ doc/doc/install.mdwn | 9 ++ doc/doc/write.mdwn | 84 +++++++++++++++++++ doc/download.mdwn | 1 + doc/index.mdwn | 11 +++ doc/news.mdwn | 4 + doc/news/git_repository_and_minor_update.mdwn | 7 ++ doc/news/news.mdwn | 3 + doc/news/online_songs.mdwn | 4 + doc/news/update_html_version.mdwn | 1 + doc/news/version_0.1.mdwn | 6 ++ doc/news/version_0.2.mdwn | 7 ++ doc/news/version_0.3.mdwn | 8 ++ doc/templates/release.mdwn | 7 ++ makefile | 16 +++- 21 files changed, 212 insertions(+), 2 deletions(-) create mode 100644 doc/bugs.mdwn create mode 100644 doc/bugs/done.mdwn create mode 100644 doc/bugs/needs_more_bugs.mdwn create mode 100644 doc/bugs/song_request.mdwn create mode 100644 doc/contact.mdwn create mode 100644 doc/doc.mdwn create mode 100644 doc/doc/faq.mdwn create mode 100644 doc/doc/install.mdwn create mode 100644 doc/doc/write.mdwn create mode 100644 doc/download.mdwn create mode 100644 doc/index.mdwn create mode 100644 doc/news.mdwn create mode 100644 doc/news/git_repository_and_minor_update.mdwn create mode 100644 doc/news/news.mdwn create mode 100644 doc/news/online_songs.mdwn create mode 100644 doc/news/update_html_version.mdwn create mode 100644 doc/news/version_0.1.mdwn create mode 100644 doc/news/version_0.2.mdwn create mode 100644 doc/news/version_0.3.mdwn create mode 100644 doc/templates/release.mdwn diff --git a/doc/bugs.mdwn b/doc/bugs.mdwn new file mode 100644 index 00000000..eedbe4f7 --- /dev/null +++ b/doc/bugs.mdwn @@ -0,0 +1,5 @@ +This is Songbook's bug list. You are welcome to submit any bugs report or feature request you want. Song requests are also welcome. + +Resolved bugs are marked as [[bugs/done]]. + +[[!inline pages="./bugs/* and !./bugs/done and !./bugs/song_request and !link(done) and !*/Discussion" actions=yes postform=yes show=0]] diff --git a/doc/bugs/done.mdwn b/doc/bugs/done.mdwn new file mode 100644 index 00000000..d3acd2a9 --- /dev/null +++ b/doc/bugs/done.mdwn @@ -0,0 +1,3 @@ +Recently fixed [[bugs]] + +[[!inline pages="./* and link(./done) and !*/Discussion" sort=mtime show=10]] diff --git a/doc/bugs/needs_more_bugs.mdwn b/doc/bugs/needs_more_bugs.mdwn new file mode 100644 index 00000000..cbd8a60f --- /dev/null +++ b/doc/bugs/needs_more_bugs.mdwn @@ -0,0 +1,2 @@ +Songbook does not have enough bugs, is it a perfect project? We doubt so. Please help create more bugs by adding code to Songbook! + diff --git a/doc/bugs/song_request.mdwn b/doc/bugs/song_request.mdwn new file mode 100644 index 00000000..1acbdaac --- /dev/null +++ b/doc/bugs/song_request.mdwn @@ -0,0 +1,3 @@ +Songs requested in [[bugs]] + +[[!inline pages="./* and link(./song_request) and !link(./done) and !*/Discussion"]] diff --git a/doc/contact.mdwn b/doc/contact.mdwn new file mode 100644 index 00000000..81180dd6 --- /dev/null +++ b/doc/contact.mdwn @@ -0,0 +1,5 @@ +A discussion board is available on . You can also contact the authors directly by mail: + + + Alexandre "Lohrun" Dupas ; + + Romain "Crep" Goffe . + diff --git a/doc/doc.mdwn b/doc/doc.mdwn new file mode 100644 index 00000000..71aafcdd --- /dev/null +++ b/doc/doc.mdwn @@ -0,0 +1,5 @@ +Documentation for Songbook. + + + How to [[install]] this software; + + How to [[write]] a new song into the books; + + There's also a [[FAQ]]. diff --git a/doc/doc/faq.mdwn b/doc/doc/faq.mdwn new file mode 100644 index 00000000..29cae491 --- /dev/null +++ b/doc/doc/faq.mdwn @@ -0,0 +1,23 @@ +Songbook frequently asked questions. + +[[!toc ]] + +## Can I propose my own song? + +Yes please do. + +## Can I suggest a song? + +Yes the bug tracker is the right place to do so. + +## Where did you find the latex style used to produce the books? + +We use a slighlty modified version of the [Songs](http://songs.sourceforge.net/) project. + +## What is the licence of this software? + +All pieces of software including Makefile, index scripts and latex style are distribued under the GPL2 licence. + +## What is the licence of the songs files? + +Song files transcribe copyrighted material. The transcription is the result of our own work. We believe that the non-commercial use of this work is fair. Copyright holders wanting us to remove songs from beeing distributed have simply to formulate their demand by email at of . \ No newline at end of file diff --git a/doc/doc/install.mdwn b/doc/doc/install.mdwn new file mode 100644 index 00000000..a2844893 --- /dev/null +++ b/doc/doc/install.mdwn @@ -0,0 +1,9 @@ +Songbook is a set of tool used to create lyrics and chords books. It is composed of a latex style and a set of script and makefile to help users to produce great quality songbook. + +Installing and running Songbook is pretty straightforward: + + tar xzvf songbook.tar.gz + cd songbook + make + +Note that you'll need make, perl, and a latex distribution that provides pdflatex to compile your first books. If you want to know more about adding songs to the songbooks, you have to learn how to [[write]] some. diff --git a/doc/doc/write.mdwn b/doc/doc/write.mdwn new file mode 100644 index 00000000..8224f571 --- /dev/null +++ b/doc/doc/write.mdwn @@ -0,0 +1,84 @@ +At one point you may want to write and add your own songs to the chordbook. Let us explain how to do this in an easy way. + +The first thing to know is that we use latex, a powerfull text processing software that produce nice looking output allowing the writter to focus on the content rather than the format. This is a programming language based on command that act as a markup. + +Command start with a backslash '\' followed by the command name. Then comes arguments of the command, if any, either between braces or square brackets. Enough for the theory, let us present the mostly common used command to produce well formated songs. + +## Main elements + +Every songs start with the following declaration where you have to replace the title and the author according to the song you are writting. + + \beginsong{Title}[by=Author] + +Then the song is composed of a succession of verses and chorus. A verse start with *\beginverse* and finish with *\endverse*. In a same way, a chorus start with *\beginchorus* and finish with *\endchorus*. + +The lyrics are typed normally between *\begin* and *\end*, but to add some chords information, you have to use a special command: for instance \[Mi] produce a **Mi** chord above the lyrics where the command is inserted. You can use whatever text as chord definition (see examples for flat, sharp or other classical notations). The following verse obtained from the song *Where is my mind* by the Pixies shows the use of these commands. + + \beginverse + With your \[Mi]feet in the air and your \[Do#m]head on the ground \[La&m] \[La] + \[Mi] Try this trick\[Do#m] and s\[La&m]pin it Ye\[La]ah, + \[Mi] Your head will coll\[Do#m]apse but there's \[La&m]nothing in it And you'll \[La]ask yourself + \endverse + +Some character have to be typed differently using latex command to produce a perfect results. The two main examples used in the current songbook are the three dots (...) and the oe character. To represent such character you have to respectively used the *{\dots}* command and the *{\oe}* command. We use braces arround the command so the command can be inserted wherever you want. Some songs use other notation for the same characters, please report any problem you may find in the current source files. + +Every songs end with the following declaration so you sould add it at the end of your file. + + \endsong + +## Chord notation + +Flat is represented using the *'&'* character: this produce a *'b'* shaped character which is the classical notation for the flat. Sharp is coded using *'#'*. Other notations are simply added as character to the main chord. For instance a *La flat minor* is noted *La&m*. + +## Optionnal elements + +Before the *\beginsong* command, you could specify the number of column you want your song to be divided into. You might have between one and three column by using the following command with the appropriate number of column. + + \songcolumns{1} + +Another great tool is the guitar tab presenting each chord played in the song. This is done using the *\gtab* command between the *\beginsong* and the first verse (*\beginverse*) or chorus (*\beginchorus*) whichever comes first. I wil not detailled how the *\gtab* command works here but I will just gives some examples with common chords. + + \gtab{Ré}{XX0232} + \gtab{Mi}{022100} + \gtab{Fa}{1,022100} + +To produce a repeat sign you should use the *\rep* command. To repeat four times a line, use the following command. + + \rep{4} + +## Example + +Here is an example of song file that could be used as a starting point to add a new song to the songbook. This is the lyrics and chord information for *Where is my mind* by the Pixies. + + \beginsong{Where Is My Mind}[by=Pixies] + + \gtab{La&m}{4,133211} + \gtab{La}{5,133211} + \gtab{Do#}{4,X13331} + \gtab{Si}{2,X13331} + + \beginverse + + \beginchorus + \[Mi]Where is my \[Do#m]mind? + \[La&m] Where is my mind?\[La] + \[Mi]Where is my \[Do#m]mind? \[La&m] \[La] + \endchorus + + \beginverse + \[Mi]Way \[Labm]out in the \[La]water see it \[Lam]swimmin' \[Do#] {\ldots} \[Si] + \endverse + + \beginverse + I was swimmin' in the Carribean + Animals were hiding behind the rock + Except the little fish + But they told me, he swears + Tryin' to talk to me to me to me + \endverse + + \endsong + +## Sending your work for inclusion + +If you add song to your songbook, why don't you send us your file. We will take a look at it and will be pleased to add it into the official songbook. As always, contributors are welcomed. diff --git a/doc/download.mdwn b/doc/download.mdwn new file mode 100644 index 00000000..83962e5b --- /dev/null +++ b/doc/download.mdwn @@ -0,0 +1 @@ +There is a git repository, at `git://git.lohrun.net/songbook.git`. diff --git a/doc/index.mdwn b/doc/index.mdwn new file mode 100644 index 00000000..4e372b3f --- /dev/null +++ b/doc/index.mdwn @@ -0,0 +1,11 @@ +Songbook is a set of tools used to produce lyricbooks and guitar chordbooks from latex songs file. It is shipped with Crep's and Lohrun's chordbook containing more than 125 songs. Crep's website, , gives more information about this project. + +* [[download]] +* [[news]] +* [[documentation|doc]] +* [[bugs]] +* [[contact]] + +---- + +This wiki is powered by [ikiwiki](http://ikiwiki.info). diff --git a/doc/news.mdwn b/doc/news.mdwn new file mode 100644 index 00000000..2237cb09 --- /dev/null +++ b/doc/news.mdwn @@ -0,0 +1,4 @@ +Here comes the annoncements of new releases, features and miscelanious news. +Songook users are recommended to subscribe to this page's RSS feed. + +[[!inline pages="./news/* and !*/Discussion" rootpage="news" show="20"]] diff --git a/doc/news/git_repository_and_minor_update.mdwn b/doc/news/git_repository_and_minor_update.mdwn new file mode 100644 index 00000000..fb01714c --- /dev/null +++ b/doc/news/git_repository_and_minor_update.mdwn @@ -0,0 +1,7 @@ +Great news! I have configured a public git repository for you to checkout the lastest development version. You can get it using: + + git clone git://git.lohrun.net/songbook.git + +I have started to work on improvement of the songbook which are available into the git repository. + +In other news, you may have noticed that my ikiwiki website is now allowing user editing. Soon you will be able to edit songs, that could be automatically used in the chordbook/lyric book. Currently you are restricted to Discussion page but feel free to register and why not asking to get editing rights. diff --git a/doc/news/news.mdwn b/doc/news/news.mdwn new file mode 100644 index 00000000..f98f426c --- /dev/null +++ b/doc/news/news.mdwn @@ -0,0 +1,3 @@ +A new presentation is used for the website. Now, upates will be provided toward a [[news]] page. Feeds are available on them to stay current on news for this site. An other section has appeared: [[songs]]. + +Soon, a download section will appear as well as a much more detailled manual. diff --git a/doc/news/online_songs.mdwn b/doc/news/online_songs.mdwn new file mode 100644 index 00000000..626f40d5 --- /dev/null +++ b/doc/news/online_songs.mdwn @@ -0,0 +1,4 @@ +After a small evening of work, I managed to have an ikiwiki plugin working that convert song files into html pages. For the moment, only 4 of them are available in [[songs]]. You can check them out. + +Further work is needed in order to complete this plugin, for instance displaying tabs; differencing chorus from verses and so on. Stay tuned! + \ No newline at end of file diff --git a/doc/news/update_html_version.mdwn b/doc/news/update_html_version.mdwn new file mode 100644 index 00000000..f7c11404 --- /dev/null +++ b/doc/news/update_html_version.mdwn @@ -0,0 +1 @@ +I have just pushed a minor update that allow html version to have a distinct appearance between chorus and verses in songs. Stay tuned for the next enhancement. \ No newline at end of file diff --git a/doc/news/version_0.1.mdwn b/doc/news/version_0.1.mdwn new file mode 100644 index 00000000..730ce03d --- /dev/null +++ b/doc/news/version_0.1.mdwn @@ -0,0 +1,6 @@ +songbook 0.1 released with [[!toggle text="these changes"]] + +[[!toggleable text=""" + + makefile: Improve handling of multiple main .tex files. For instance, it is now possible to have a lyricbook.tex and chordbook.tex each of them generating a pdf file containing something different. It also now take cares of dependencies over other .tex file or other special files (songs.sbd for instance). + + songs.sty: Minor change to allow songs to contain fret numbers in tabs. The separator is now ',' instead of ':'. +"""]] diff --git a/doc/news/version_0.2.mdwn b/doc/news/version_0.2.mdwn new file mode 100644 index 00000000..365bd168 --- /dev/null +++ b/doc/news/version_0.2.mdwn @@ -0,0 +1,7 @@ +songbook 0.2 released with [[!toggle text="these changes"]] + +[[!toggleable text=""" + + make-index: Alphabetical ordering and hierachy by the first letter now for both title and authors. Do not ignore article before a song's or author's name. + + makefile: Simplified makefile (do not use songs/song.sbd anymore). + + songs: New version from Crep with tabs for every songs. +"""]] diff --git a/doc/news/version_0.3.mdwn b/doc/news/version_0.3.mdwn new file mode 100644 index 00000000..ec4266c0 --- /dev/null +++ b/doc/news/version_0.3.mdwn @@ -0,0 +1,8 @@ +songbook 0.3 released with [[!toggle text="these changes"]] + +[[!toggleable text=""" + + Major update with many new songs (total of 125 songs) - Crep, Lohrun + + Corrections of a lot of mistakes - Crep + + Include image support - Crep + + Add make-html utility - Lohrun +"""]] diff --git a/doc/templates/release.mdwn b/doc/templates/release.mdwn new file mode 100644 index 00000000..93cd450d --- /dev/null +++ b/doc/templates/release.mdwn @@ -0,0 +1,7 @@ +News for Songbook : + + + + +Songbook released with [[!toggle text="these changes" id="changelog"]] +[[!toggleable id="changelog" text=""""""]] diff --git a/makefile b/makefile index 5fa79aac..9900d7c4 100644 --- a/makefile +++ b/makefile @@ -29,6 +29,12 @@ SONGS_SRC = $(shell ls songs/*/*.sg) MAKE_INDEX=./make-index +ifeq ($(shell which ikiwiki),) +IKIWIKI=echo "** ikiwiki not found" >&2 ; echo ikiwiki +else +IKIWIKI=ikiwiki +endif + # Get dependencies (that can also have dependencies) define get_dependencies deps=`perl -ne '($$_)=/^[^%]*\\\(?:include|input)\{(.*?)\}/;@_=split /,/; foreach $$t (@_) { print "$$t "}' $<` @@ -46,7 +52,7 @@ endef ############################################################ ### Cibles -default: pdf +default: pdf documentation ps: LATEX = latex ps: $(PSF) @@ -56,7 +62,7 @@ pdf: LATEX = pdflatex pdf: $(PDF) xpdf $< -clean: +clean: cleandoc @rm -f $(SRC:%.tex=%.d) @rm -f $(CIBLE:%=%.aux) @rm -f $(CIBLE:%=%.toc) @@ -70,6 +76,12 @@ cleanall: clean depend: +documentation: + $(IKIWIKI) doc html -v --wikiname "Songbook Documentation" --plugin=goodstuff + +cleandoc: + @rm -rf "doc/.ikiwiki" html + ############################################################ $(PSF): LATEX = latex