diff options
Diffstat (limited to 'data/doc/sisu/org')
-rw-r--r-- | data/doc/sisu/org/bugs/sisu_bugs.org | 403 | ||||
-rw-r--r-- | data/doc/sisu/org/done/sisu-done.org | 1987 | ||||
-rw-r--r-- | data/doc/sisu/org/in_progress/sisu_asciidoc.org | 140 | ||||
-rw-r--r-- | data/doc/sisu/org/in_progress/sisu_docbook.org | 77 | ||||
-rw-r--r-- | data/doc/sisu/org/in_progress/sisu_fictionbook.org | 86 | ||||
-rw-r--r-- | data/doc/sisu/org/in_progress/sisu_markdown.org | 139 | ||||
-rw-r--r-- | data/doc/sisu/org/in_progress/sisu_rst.org | 236 | ||||
-rw-r--r-- | data/doc/sisu/org/in_progress/sisu_todo.org | 192 | ||||
-rw-r--r-- | data/doc/sisu/org/sisu.org | 853 | ||||
-rw-r--r-- | data/doc/sisu/org/sisu_packaging.org | 269 |
10 files changed, 4382 insertions, 0 deletions
diff --git a/data/doc/sisu/org/bugs/sisu_bugs.org b/data/doc/sisu/org/bugs/sisu_bugs.org new file mode 100644 index 00000000..0571e6d2 --- /dev/null +++ b/data/doc/sisu/org/bugs/sisu_bugs.org @@ -0,0 +1,403 @@ +#+PRIORITIES: A F E +#+OPTIONS: ^:nil _:nil +** bugs :bug: + +*** misc, unclassified + +**** TODO UNDERWAY (6.0.5) [#B] exclude heading where possible marker '-#' not distinguished from unnumbered heading '~#' + + * ~# is general & means no ocn (for any object to which it is applied) + * -# is relevant only for 1~ dummy headings & instructs that they should be + removed from output where possible + * where -# is used on any other objects, it is treated the same way as ~# + +**** TODO [#B] collapsed level work out logic where dummy lev1 heading + + * exclude heading where lev1 '-#' + * means subsequent headings & text belong to parent heading (of lev1 -#) 1 level up + * ponder + +*** DBT Outstanding bugs -- sisu caught by removal of ruby-dbi + +**** TODO ONGOING #746740 [n|u] manpages incomplete + +Date: Sat, 03 May 2014 08:45:49 +0200 +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +Subject: manpages incomplete +Package: sisu +Version: 5.3.4-1 +Tag: upstream +Severity: normal + +sisu supports options like --verbose or --no-manifest, but they are not +listed in the sisu manpage. + +***** NOTES/COMMENTS + +documentation for sisu does lag a bit and has omissions, but I think you will +find that --verbose is documented, and --no-* options are listed under --exc-* +to which there is a pointer --no-manifest works but is actually +--no-links-to-manifest and is listed under aliases --exc-links-to-manifest and +--exc-manifest-links + +Will leave bug open as a reminder that updating is necessary and as there are +no doubt numerous issues for which this could be (re)opened + +**** TODO #746742 [n|u] please implement --no-metadata similar to --no-manifest + +Date: Sun, 13 Apr 2014 16:12:13 +0200 +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +Subject: --no-manifest not working anymore +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when running sisu-pdf with --no-manifest, the output (pdf) still +contains the sisu manifest at the end of the document. + +Regards, +Daniel + +*** DBT Outstanding bugs -- Wishlist items; Unclassified (24 bugs) :debian:dbt:wishlist: + +**** TODO [#D] #744352 [w|u] sisu output: aligning margin numbers when using 'code' + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744352> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: 744352@bugs.debian.org +Subject: Re: sisu output: too many margin numbers +Date: Sun, 13 Apr 2014 17:27:10 +0200 +retitle 744352 sisu output: aligning margin numbers when using 'code' +severity 744352 wishlist +thanks + +sorry, i've looked wrongly at the output, the problem is simply an +aligning issue. it looks like that: + + foo bar. [1] + [2] + baz + + foo bar baz. [3] + +rather than: + + foo bar. [1] + + baz [2] + + foo bar baz. [3] + +Regards, +Daniel + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: too many margin numbers +Date: Sun, 13 Apr 2014 12:28:14 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when using the following code: + +foo bar. + +code{ + + baz + +}code + +foo bar baz. + +the result in the output (pdf) is: + +foo bar. [1] + [2] +baz [3] + [4] +foo bar baz. [5] + +the '[n]' designates the margin number at the right site of the page. + +the problem is that sisu gives margin numbers to *empty* lines, which is +wrong. margin numbers should only be assigned to actual content. + +Regards, +Daniel + +***** NOTES/COMMENTS + +issue with pdf, look again, consider, this is cosmetic, a fix should be found, +but is not striaghtforward alignment issue for code blocks not so easy to fix +in some outputs, have so far ignored this is an issue with other types of text +block as well + +reason why this has not been addressed especially with code blocks: +the easiest fix would be to place the numbering at the end of the first line of +a code block however, as it is now, if you copy & paste a block of code you +should get the code if numbering is moved down to the first line, a copy of the +code block will inlcude the extraneous (to the code) object number which is to +my mind a bigger problem + +That said re pdf, LaTeX XeTeX are flexible, it may be possible to drop the ocn +at the start of a code block lower on its line so that it is closer to the code +that follows + +**** TODO [#C] #744354 [w|u] sisu output: please do not add '<' and '>' around urls + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: please do not add '<' and '>' around links +Date: Sun, 13 Apr 2014 12:28:37 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when using urls in sisu like this: + + http://example.org + +sisu then creates in the output (pdf) links like this: + + <http://example.org> + +Please do not automagically add a '<' and '>' around urls. If the user +wants them, he would add one. + +Regards, +Daniel + +***** NOTES/COMMENTS + +is sisu default behavior, +would need to make configurable +url_visual_delimiters: '<>' +look into later + + +**** TODO [#B] #744390 [w|u] sisu: empty sections are ignored + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744390> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu: empty sections are ignored +Date: Sun, 13 Apr 2014 17:09:32 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +if you have the following sisu syntax: + + :B~ foo + + 1~ foo1 + + foo1. + + 1~ foo2 + + foo2. + + :B~ bar + + 1~ bar1 + + 1~ bar2 + + :B~ baz + + 1~ baz1 + + 1~ baz2 + +then anything (including and) after ':B~ bar' is ignored entirely. + +***** NOTES/COMMENTS + +further info, have not yet been able to duplicate, +seemed to work (checked pdf & html (scroll & seg)) +was not able to reproduce +will look again + +**** TODO [#D] #744395 [w|u] sisu output: half-page title page in landscape output + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744395> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu output: half-page title page in landscape output +Date: Sun, 13 Apr 2014 17:38:03 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +in a4 landscape output, there's always two pages on one page, which is +nice; except for the title page which spans over the whole page. + +it would be nice if the first page would be consistent to the same +scheme like the rest of the document - spanning only over the half of +the page. + +Regards, +Daniel + +***** NOTES/COMMENTS + +think about, should be fairly easily done, but am reluctant + +note the page numbering in landscape, the two landscape columns are given a single page number +it is really a landscape two column per-page text, provided primarily for screen viewing or +other convenience if found + +(many viewers provide two page per screen presentations, which would result in an effect similar to the one requested +the issue I guess might arise in that they are not printable on a single page? ... +but then the current settings are arguably justified) + +**** TODO [#C] #744396 [w|u] sisu output: "european" toc indenting + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744396> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu output: "european" toc indenting +Date: Sun, 13 Apr 2014 17:40:53 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +by default, latex uses the following indenting in the TOC: + + 1. foo + 1.1 bar1 + 1.1.1 baz + 1.2 bar2 + +there's a latex option that i don't remember off-hand to have the +indenting like it's common in europe: + + 1. foo + 1.1 bar1 + 1.1.1 baz + 1.2 bar2 + +it would be nice if sisu could let the used decide which indenting style +to use for TOCs. + +Regards, +Daniel + +***** NOTES/COMMENTS + +will look at: should be possible; requires a configuration option + +**** TODO [#C] #744407 [w|u] sisu: possibility to influence content/formating of the title page + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744407> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu: possibility to influence content/formating of the title page +Date: Sun, 13 Apr 2014 18:32:14 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +by default, the title page (in the pdf output) shows @title and @creator. + +it would be nice if there would be a possibility to influence the +formatting (e.g. to have the title written in bold), and to have +additional possibilities to influence the content on the title page +(like the date or version, an url, or other text strings). + +Regards, +Daniel + +***** NOTES/COMMENTS + +consider, work on possibly, later + +**** TODO [#C] #744409 [w|u] sisu output: urls in code blocks are not linkified + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744409> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu output: urls in code blocks are not linkified +Date: Sun, 13 Apr 2014 18:41:09 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +it would be nice if urls written withiin code{...}code blocks would also +be automatically transformed into a link within the output (html). + +Regards, +Daniel + +***** NOTES/COMMENTS + +consider, so far code blocks are pretty much untouched ... not tampered with, +this could be done though + +**** TODO [#C] #744685 [w|u] sisu output: copy&past-able wrapped code blocks + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744685> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu output: copy&past-able wrapped code blocks +Date: Sun, 13 Apr 2014 19:04:01 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +if a line within a 'code{...}code' block is longer and needs to be +wrapped, sisu indicates the wrapping with an 'arrow' (←) symbol, which +is nice. + +it would be even nicer if the arrow would not 'selectable', so that when +you mark the line spanning over two lines with your mouse, the arrow is +not selected and thus not copy&pasted. + +i don't know how to do this, but it's possible within pdfs, as can be +seen in lots of pdfs in the internet. + +Regards, +Daniel + +***** NOTES/COMMENTS + +find out how and implement, further feedback on appropriate xetex tools welcome + +[Note: if can be applied to random characters, use may be of interest for +object numbers as well!] + +**** TODO [#C] #744734 [w|u] sisu output: replace all occurences of (C) rather than the first only + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu output: replace all occurences of (C) rather than the first only +Date: Mon, 14 Apr 2014 06:11:13 +0200 + +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +if you have a '(C)' in :copyright:, it is automatically replaced with a +copyright symbol, which is nice, however, it sisu does that with the +first occurence only. + +so if you use: + + :copyright: (C) john doe<br />(C) jane doe + +then the second occurence is not replaced and that combination looks +very ugly. i suggest you replace all occurences of '(C)' to the +copyright symbol automatically. + +Regards, +Daniel + diff --git a/data/doc/sisu/org/done/sisu-done.org b/data/doc/sisu/org/done/sisu-done.org new file mode 100644 index 00000000..f39fcee1 --- /dev/null +++ b/data/doc/sisu/org/done/sisu-done.org @@ -0,0 +1,1987 @@ +#+PRIORITIES: A F E +(emacs:evil mode gifts a "vim" of "alternative" powers! ;) + +* General +** Finding +*** source + +http://git.sisudoc.org/gitweb/ + +sisu git repo: +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary + +sisu-markup-samples git repo: +http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary + +*** mailing list +sisu at lists.sisudoc.org + +http://lists.sisudoc.org/listinfo/sisu + +** irc oftc sisu + +** home pages + * <http://www.sisudoc.org/> + * <http://search.sisudoc.org/> + * <http://www.jus.uio.no/sisu> + +** Installing sisu + +*** where you take responsibility for having the correct dependencies + +Provided you have *Ruby*, *SiSU* can be run. + +SiSU should be run from the directory containing your sisu marked up document +set. + +This works fine so long as you already have sisu external dependencies in +place. For many operations such as html, epub, odt this is likely to be fine. +Note however, that additional external package dependencies, such as texlive +(for pdfs), sqlite3 or postgresql (for search) should you desire to use them +are not taken care of for you. + +**** run off the source tarball without installation + +RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) +.......................................................... + +***** 1. Obtain the latest sisu source + +using git: + +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log + + git clone git://git.sisudoc.org/git/code/sisu.git + +or, identify latest available source: + +https://packages.debian.org/sid/sisu +http://packages.qa.debian.org/s/sisu.html +http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org + +http://sisudoc.org/sisu/archive/pool/main/s/sisu/ + +and download the: + + sisu_5.4.5.orig.tar.xz + +using debian tool dget: + +The dget tool is included within the devscripts package +https://packages.debian.org/search?keywords=devscripts +to install dget install devscripts: + + apt-get install devscripts + +and then you can get it from Debian: + dget -xu http://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc + +or off sisu repos + dget -x http://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc +or + dget -x http://sisudoc.org/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc + +***** 2. Unpack the source + +Provided you have *Ruby*, *SiSU* can be run without installation straight from +the source package directory tree. + +Run ruby against the full path to bin/sisu (in the unzipped source package +directory tree). SiSU should be run from the directory containing your sisu +marked up document set. + + ruby ~/sisu-5.4.5/bin/sisu --html -v document_name.sst + +This works fine so long as you already have sisu external dependencies in +place. For many operations such as html, epub, odt this is likely to be fine. +Note however, that additional external package dependencies, such as texlive +(for pdfs), sqlite3 or postgresql (for search) should you desire to use them +are not taken care of for you. + +**** gem install (with rake) + +(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install +the gem + +Provided you have ruby & rake, this can be done with the single command: + + rake gem_create_build_install + +to build and install sisu v5 & sisu v6, alias gemcbi + +separate gems are made/installed for sisu v5 & sisu v6 contained in source. + +to build and install sisu v5, alias gem5cbi: + + rake gem_create_build_install_stable + +to build and install sisu v6, alias gem6cbi: + + rake gem_create_build_install_unstable + +for individual steps (create, build, install) see rake options, rake -T to +specify sisu version for sisu installed via gem + + gem search sisu + + sisu _5.4.5_ --version + + sisu _6.0.11_ --version + +to uninstall sisu installed via gem + + sudo gem uninstall --verbose sisu + +For a list of alternative actions you may type: + + rake help + + rake -T + +Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> + +**** installation with setup.rb + +this is a three step process, in the root directory of the unpacked *SiSU* as +root type: + +ruby setup.rb config +ruby setup.rb setup +#[as root:] +ruby setup.rb install + +further information: +<http://i.loveruby.net/en/projects/setup/> +<http://i.loveruby.net/en/projects/setup/doc/usage.html> + + ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install + +*** Debian install + +*SiSU* is available off the *Debian* archives. It should necessary only to run +as root, Using apt-get: + + apt-get update + + apt get install sisu-complete + +(all sisu dependencies should be taken care of) + +If there are newer versions of *SiSU* upstream, they will be available by +adding the following to your sources list /etc/apt/sources.list + +#/etc/apt/sources.list + +deb http://www.jus.uio.no/sisu/archive unstable main non-free +deb-src http://www.jus.uio.no/sisu/archive unstable main non-free + +The non-free section is for sisu markup samples provided, which contain +authored works the substantive text of which cannot be changed, and which as a +result do not meet the debian free software guidelines. + +*SiSU* is developed on *Debian*, and packages are available for *Debian* that +take care of the dependencies encountered on installation. + +The package is divided into the following components: + + *sisu*, the base code, (the main package on which the others depend), without + any dependencies other than ruby (and for convenience the ruby webrick web + server), this generates a number of types of output on its own, other + packages provide additional functionality, and have their dependencies + + *sisu-complete*, a dummy package that installs the whole of greater sisu as + described below, apart from sisu -examples + + *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated + + *sisu-postgresql*, dependencies used by sisu to populate postgresql database + (further configuration is necessary) + + *sisu-sqlite*, dependencies used by sisu to populate sqlite database + + *sisu-markup-samples*, sisu markup samples and other miscellany (under + *Debian* Free Software Guidelines non-free) + + *SiSU* is available off Debian Unstable and Testing [link: + <http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>] + [^1] install it using apt-get, aptitude or alternative *Debian* install tools. + +* Markup :sisu:markup: + +** sisu + +#% structure - headings, levels + * headings (A-D, 1-3) + * inline + 'A~ ' NOTE title level + 'B~ ' NOTE optional + 'C~ ' NOTE optional + 'D~ ' NOTE optional + '1~ ' NOTE chapter level + '2~ ' NOTE optional + '3~ ' NOTE optional + '4~ ' NOTE optional :consider: + * node + * parent + * children + +#% font face NOTE open & close marks, inline within paragraph + * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold + * bold '!{ ... }!' + * italics '/{ ... }/' + * underscore '_{ ... }_' + * superscript '^{ ... }^' + * subscript ',{ ... },' + * strike '-{ ... }-' + * add '+{ ... }+' + * monospace '#{ ... }#' +#% para NOTE paragraph controls are at the start of a paragraph + * a para is a block of text separated from others by an empty line + * indent + * default, all '_1 ' up to '_9 ' + * first line hang '_1_0 ' + * first line indent further '_0_1 ' + * bullet + [levels 1-6] + '_* ' + '_1* ' + '_2* ' + * numbered list + [levels 1-3] + '# ' + +#% blocks NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be + * code + * [type of markup if any] + * poem + * group + * alt + * tables +#% boxes + NOTE grouped text with code block type color & possibly default image, warning, tip, red, blue etc. decide [NB N/A not implemented] + +#% notes NOTE inline within paragraph at the location where the note reference is to occur + * footnotes '~{ ... }~' + * [bibliography] [NB N/A not implemented] + +#% links, linking + * links - external, web, url + * links - internal + +#% images [multimedia?] + * images + * [base64 inline] [N/A not implemented] + +#% object numbers + * ocn (object numbers) + automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided) + +#% contents + * toc (table of contents) + autogenerated from structure/headings information + * index (book index) + built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text + +#% breaks + * line break ' \\ ' inline + * page break, column break ' -\\- ' start of line, breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. + * page break, page new ' =\\= ' start of line, breaks the page, starts a new page. + * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs) + +#% book type index + +#% comment + * comment + +#% misc + * term & definition + +** proposals/additions + +*** TODO [#B] markup syntax code block, indicate syntax of code :feature: + ``` code:ruby + +*** TODO [#C] colored boxes round text :feature:ponder: + ``` box:red (select color of box) + ``` box:warn ``` box:tip (some default boxes? decide) + ``` box:red:"Warn" (select color and lead text of box, else instead + select color box & use regular single line bold markup ^!_ Warn$) + +*** TODO [#D] blockquotes implement? :feature:ponder: + ``` quote + not sure how best to represent + +*** TODO [#D] bibliography :feature:ponder: + +*** TODO speaker, as e.g. play (irc?) :feature:ponder: + ``` Ophelia: + ::Ophelia + +*** TODO [#F] time stamp (e.g. for irc, video text?):feature:ponder: + ``` 04:03 + ``` 04:03 ... 07:12 + ``` 04:03 + 03:09 + ``` 12:04:03 + ``` 12:04:03 ... 12:07:12 + ``` 12:04:03 + 03:09 + probably not worth the effort, as time stamp is an alternative + identifying number (to ocn, and ∴ sisu objects not ideal) + +*** TODO book index, alternative based on search within text + +** syntax hilighting + +*** vim +data/sisu/conf/editor-syntax-etc/vim/ +data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim + +*** emacs +data/sisu/conf/editor-syntax-etc/emacs/ +data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el + +* Document Abstraction :sisu:doc_abstr: + +** TODO [#D] XML middle layer? + +*** XMLda sisu + consder alternative sisu layer in XML + +*** TODO [#D] RelaxNG sisu + +* Output :sisu:output: +** New outputs to consider + +*** XML :xml: +%% xml, docbook.txt fictionbook.txt xldl.txt lml.txt tei.txt emacs.txt +<http://xml.silmaril.ie/> +<http://www.xml.com/> +<http://programming.oreilly.com/2012/08/shrinking-and-stretching-the-boundaries-of-markup.htmlhttp://programming.oreilly.com/2012/08/shrinking-and-stretching-the-boundaries-of-markup.html> + +<http://broadcast.oreilly.com/2012/03/xmls-dialect-problem.html> + +xml editor vim emacs +<http://chimera.labs.oreilly.com/books/1234000000058/ch01.html#which_xml_editor_should_i_use> +nXML plugin +<http://blog.tommorris.org/post/2456183251/emacs-and-nxml-survival-guide> +<http://johnbokma.com/mexit/2008/10/01/nxml-emacs-how-to.html> +<http://www.emacswiki.org/cgi-bin/wiki/NxmlModeForXHTML> +<http://www.xmlhack.com/read.php_item=2061> +<http://infohost.nmt.edu/tcc/help/pubs/nxml/index.html> +emacs.txt evil.txt + +<http://www.oreillynet.com/xml/blog/2005/10/smart_quotes_and_more_in_vim_a.html> +<http://stackoverflow.com/questions/1430164/differences-between-emacs-and-vim> + +To validate a book.xml file using xmllint, run the following command: +$ xmllint --postvalid --xinclude --noout book.xml + +The default location where xmllint will look for the catalog file is +/etc/xml/catalog. Alternatively, you can set the environment variable +XML_CATALOG_FILES to define another default location for catalog +files. Once you’ve got the DTD and catalog set up locally, you can +validate as before: +$ xmllint --postvalid --xinclude --noout book.xml + +%% Docbook +docbook.txt + +%% Fictionbook +fictionbook.txt + +%% XLDL +xldl.txt + +%% Literature Markup Language +lml.txt + +%% Text Encoding Initiative +tei.txt + +**** TODO [#B] docbook :feature: + +***** urls +#% docbook book xml.txt +<http://www.docbook.org> +<http://www.sagehill.net/docbookxsl/index.html> +<http://wiki.docbook.org/> +<http://www.docbook.org/tdg5/en/html/> +<http://www.docbook.org/tdg5/en/html/docbook.html> +<http://www.docbook.org/tdg5/en/html/ch01.html> +<http://www.docbook.org/tdg5/en/html/ch02.html> +<http://www.sagehill.net/docbookxsl/index.html> + +<http://www.docbook.org/schemas/5x> +<http://www.docbook.org/xml/5.0/> + +<http://infohost.nmt.edu/tcc/help/pubs/docbook5/web/index.html> + +<http://docbook.org/xml/5.0/rng/docbook.rng> +<http://docbook.org/xml/5.0/rng/docbook.rnc> + +<http://www.cuddletech.com/blog/pivot/entry.php?id=509> + +***** rb file +lib/sisu/v6/xml_docbook5.rb + +***** transformations :transform:markup_docbook: +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [] node (child, parent ...) + +#% font face + [] bold + [] italics + [] underscore + [] superscript + [] subscript + [] strike + [] add + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + +#% blocks + <http://www.docbook.org/tdg5/en/html/literallayout.html> + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + <http://www.docbook.org/tdg5/en/html/toc.html> + [] index (book index) + +#% misc + +**** TODO [#D] fictionbook :feature: + +***** urls +#% fictionbook xml.txt +<http://en.wikipedia.org/wiki/FictionBook> +<http://fictionbook.org/index.php/Eng:FictionBook> +<http://fictionbook.org/index.php/Eng:Articles> +<http://fictionbook.org/index.php/Eng:Documentations> +<http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1> +<http://www.fictionbook.org/index.php/Eng:FictionBook> +<http://fictionbook-lib.org/> +<http://fictionbook-lib.org/browse.php> +<http://wiki.mobileread.com/wiki/FB2> + +***** rb file +lib/sisu/v6/xml_fictionbook2.rb + +***** transformations :transformations:markup_fictionbok: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [] node (child, parent ...) + +#% font face + [] bold + [] italics + [] underscore + [] superscript + [] subscript + [] strike + [] add + [] monospace + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + +#% blocks + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + [] column break + [] page break + +#% comment + [] comment + +#% misc + +<http://en.wikipedia.org/wiki/FictionBook> +<http://fictionbook.org/index.php/Eng:FictionBook> +<http://fictionbook.org/index.php/Eng:Articles> +<http://fictionbook.org/index.php/Eng:Documentations> +<http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1> +<http://www.fictionbook.org/index.php/Eng:FictionBook> + +<http://www.fictionbook.org/index.php/%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0_%D0%B2_FB2> + +<https://addons.mozilla.org/en-US/firefox/addon/fb2-reader/> + +**** TODO [#D] XLDL :feature: + +***** urls +%% xml.txt xldl - novels, stories, poems +Name: XLDL - an XML doctype for novels, stories, poems, playsName: XLDL - an XML doctype for novels, stories, poems, plays +<http://www.ister.org/code/xldl/> +<http://www.ister.org/code/xldl/doc/xldl.dtd.html> +<line> <stanza> + +**** TODO [#E] Literature Markup Language - <LML /> :feature: + +***** urls +%% Literature Markup Language - <LML /> +<http://hoffmann.bplaced.net/lml/> +"It is assumed, that there are three quite different techniques to provide text, +respectively three types of text, this is prose and poetry and code (for +example source code of computer programs or from markup languages)." +Suggestions and Ideas for Literature Markup Language - <LML /> 1.1 +<http://hoffmann.bplaced.net/lml/lml1.1.php> + +**** TODO [#E] TEI Lite (Text Encoding Initiative) :feature: + +***** urls +%% TEI Lite (Text Encoding Initiative) +<http://www.tei-c.org/Guidelines/Customization/Lite/> +<http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_lite.doc.html> + +*** Text :txt: + +sisu_markup.txt asciidoc.txt markdown.txt textile.txt rst.txt + +**** TODO [#D] asciidoc :feature: + +***** urls +#% asciidoc +<http://asciidoc.org/> +<http://asciidoctor.org/> +<http://www.methods.co.nz/asciidoc/> +<http://en.wikipedia.org/wiki/AsciiDoc> + +cheatsheets +<http://powerman.name/doc/asciidoc> +<http://powerman.name/doc/asciidoc-index> + +<http://www.methods.co.nz/asciidoc/asciidoc.txt> +<http://www.methods.co.nz/asciidoc/userguide.html> + +<http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html> +<http://www.methods.co.nz/asciidoc/asciidoc.html> +<http://www.methods.co.nz/asciidoc/chunked/index.html> + +***** rb file +lib/sisu/v6/txt_asaciidoc.rb + +***** transformations :transformations:markup_asciidoc: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-4) (decoration) + [] inline + '== ' + '=== ' + '==== ' + '===== ' + '' + '' + [] underscore + '-' + '~' + '^' + '+' + '' ['.' proposed] + '' ['.' proposed] + [] node (child, parent ...) + +#% font face + [open & close marks] + [] bold + '*' + [] italics + '_' + [] underscore + '' + [] superscript + '^' + [] subscript + '~' + [] strike + '-' + [] add + [] monospace + '+' + '`' pass markup through unchanged, monospace code + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + [levels 1-6] + '*' + '**' + '***' + '****' + '*****' + '*******' + [] numbered list + [levels 1-3] + '. ' number + '.. ' lower alpha + '... ' lower roman + '.... ' upper alpha + '..... ' upper roman + +#% blocks + [] code + [source,perl] + ---- + code here + ---- + [] [type of markup if any] + [] poem + [] group + ---- + grouped text here, actually a listing block + ---- + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + http://google.com[Google Search] + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + "+\n" + forced + + line break + [] horizontal rule + [] column break + [] page break + +#% comment + [] comment + // + +#% misc + + [] term & definition +Term 1:: Definition 1 +Term 2:: Definition 2 +[horizontal] + Term 2.1;; + Definition 2.1 + Term 2.2;; + Definition 2.2 + +**** TODO [#E] markdown :feature: + +***** urls +#% markdown +<http://daringfireball.net/projects/markdown/> +<http://daringfireball.net/projects/markdown/syntax> +<http://daringfireball.net/projects/markdown/basics> +<http://en.wikipedia.org/wiki/Markdown> +<https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> +<http://whatismarkdown.com/> + +Markdown supports two styles of headers, Setext and atx +Setext +<http://docutils.sourceforge.net/mirror/setext.html> +<http://en.wikipedia.org/wiki/Setext> +atx +<http://www.aaronsw.com/2002/atx/intro> + +<http://support.iawriter.com/help/kb/general-questions/markdown-syntax-reference-guide> +<http://bywordapp.com/markdown/syntax.html> +<http://stackoverflow.com/editing-help> + +<http://support.mashery.com/docs/customizing_your_portal/Markdown_Cheat_Sheet> +<http://warpedvisions.org/projects/markdown-cheat-sheet.md> +<http://nestacms.com/docs/creating-content/markdown-cheat-sheet> +<https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> + +<https://help.github.com/articles/github-flavored-markdown> +<http://lifehacker.com/5943320/what-is-markdown-and-why-is-it-better-for-my-to+do-lists-and-notes> + +#% pandoc markdown +<http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html> +<http://johnmacfarlane.net/pandoc/README.html> +<http://johnmacfarlane.net/pandoc/demo/example19/Pandoc_0027s-markdown.html> +<http://johnmacfarlane.net/pandoc/> +<http://johnmacfarlane.net/pandoc/epub.html> +<http://johnmacfarlane.net/pandoc/faqs.html> + +#% multimarkdown +<http://fletcher.github.io/peg-multimarkdown/> + +#% markdown pandoc v multimarkdown +<https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown> + +#% rST v markdown +<http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext> + +***** rb file +lib/sisu/v6/txt_markdown.rb + +***** transformations :transformations:markup_markdown: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [inline 1-5] + '#' + '##' + '###' + '####' + '#####' + '######' + [underscore 1-5] + '=' + '-' + #'~' + #'^' + #'+' + [] node (child, parent ...) + +#% font face + [open & close marks] + [] bold + '**' + [] italics + '*' + [] underscore + '' + [] superscript + '' + [] subscript + '' + [] strike + '' + [] add + [] monospace + '`' + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + '*' + [] numbered list + '0.' + +#% blocks + [] code + ' ' #indent at least 4 spaces + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + (three or more asterisks hypens or underscores) + * * * + *** + ***** + - - - + ___ + [] column break + [] page break + +#% misc + +**** TODO [#F] rst :feature: + +***** urls +#% rST +<http://docutils.sourceforge.net/rst.html> +<http://docutils.sourceforge.net/docs/user/rst/quickref.html> +<http://docutils.sourceforge.net/docs/user/rst/quickstart.html> +<http://en.wikipedia.org/wiki/ReStructuredText> +<http://sphinx-doc.org/rest.html> + +<http://stackoverflow.com/questions/2746692/restructuredtext-tool-support> + +#% rST v markdown +<http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext> + +***** rb file +lib/sisu/v6/txt_rst.rb + +***** transformations :transformations:markup_rst: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [inline] + N/A + [underscore] + Titles are underlined (or over- and underlined) with a printing + nonalphanumeric 7-bit ASCII character. Recommended choices are + "= - ` : ' " ~ ^ _ * + # < >". The underline/overline must be at + least as long as the title text. + '=' + '-' + '`' + ':' + "'" + '"' + + [] node (child, parent ...) + +#% font face + [] bold + '**' + [] italics + '*' + [] underscore + '+' + [] superscript + '^' + [] subscript + [] strike + '-' + [] add + [] monospace + '``' + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + "-", "*" or "+" + '-' + [] numbered list + '#.' + +#% blocks + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [binary] + Footnote references, like [5]_. + Note that footnotes may get + rearranged, e.g., to the bottom of + the "page". + .. [5] A numerical footnote. + -- + Autonumbered footnotes are + possible, like using [#]_ and [#]_. + .. [#] This is the first one. + .. [#] This is the second one. + + [] [bibliography?] + +#% links, linking + [] links - external, web, url + Typical result + External hyperlinks, like Python_. + .. _Python: <http://www.python.org/> + or + External hyperlinks, like `Python + <http://www.python.org/>`_. + [] links - internal + Internal crossreferences, like example_. + .. _example: + + This is an example crossreference target. + -- + Titles are targets, too + ======================= + Implict references, like `Titles are + targets, too`_. + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + [] column break + [] page break + +#% misc + +**** TODO [#F] textile :feature: + +***** urls +#% textile +<http://en.wikipedia.org/wiki/Textile_(markup_language)> +v2.4 +<http://www.txstyle.org/> +v2 +<http://redcloth.org/hobix.com/textile/> + +***** rb file +lib/sisu/v6/txt_textile.rb + +***** transformations :transformations:markup_textile: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [inline] + h1(#id). An HTML first-level heading + h2. An HTML second-level heading + h3. An HTML third-level heading + h4. An HTML fourth-level heading + h5. An HTML fifth-level heading + h6. An HTML sixth-level heading + [underscore] + N/A + + [] node (child, parent ...) + +#% font face + [] bold + *bold text* + [] italics + _italic text_ + [] underscore + +underlined text+ + [] superscript + ^TM^ + [] subscript + ~subscript~ + [] strike + -strikethrough text- + [] add + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + * bulleted list + ** 2-level + +#% blocks + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + |Table | with two columns | + |and two | rows | + +#% notes + [] footnotes + Text with a link to some reference[1] + fn1. Footnote explanation + [] [bibliography?] + +#% links, linking + [] links - external, web, url + "(classname)link text(title tooltip)":link_address + "Link to Wikipedia":http://www.wikipedia.org + [] links - internal + +#% images [multimedia?] + [] images + !http://commons.wikimedia.org/wiki/Special:Filepath/Wikipedia-logo-en.png! + !imageurl(alt text)! + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + [] column break + [] page break + +#% misc + [] *_bold italic text_* + [] *-bold strikethrough text-* + [] *_-bold italic strikethrough text-_* + [] *+bold underlined text+* + [] *_+italic underlined text+_ + [] *_+bold italic underlined text+_ + [] *_-+bold italic strikethrough underlined text+-_* + %{font-size:18pt}font size% + %{color:red}text in red% + # Chapter 1 + +#% notes +heading inline only +footnotes uses marker and endnote, check + +** Improvements + +*** HTML + +*** XML + +*** --strict mode (html w3c compliant ocn etc.) + +* Code (ruby) :sisu:code: + +** code enhancements :enhance: + +*** TODO [#D] directory & path, use ruby directory tools + +*** TODO [#D] document url shortcut, allow addition of alternative dir stub +(e.g. viral Spiral) + +** code refactoring :refactor: + +*** ruby 2.1 + +**** DONE make sure sisu works + +** bugs :bug: + +*** misc, unclassified + +**** DONE (6.0.5) [#B] sisu should give warning when part of minimal essential structure is missing :processing:fix: + +work through testing for as many of these as possible + +minimal content/structure requirement: +[metadata] + @title: + @creator: +[levels] + A~ (level A [title]) + 1~ (at least one level 1 [segment/(chapter)]) +test what happens in the absence of each + +structure rules (document heirarchy, heading levels): + + there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any) + sisu has the fllowing levels: + + A~ [title] . required (== 1) followed by B~ or 1~ + B~ [part] * followed by C~ or 1~ + C~ [subpart] * followed by D~ or 1~ + D~ [subsubpart] * followed by 1~ + 1~ [segment (chapter)] + required (>= 1) followed by text or 2~ + text * followed by more text or 1~, 2~ or relevant part *(B~ if none other used; if C~ is last used: C~ or B~; if D~ is used: D~, C~ or B~) + 2~ [subsegment] * followed by text or 3~ + text * followed by more text or 1~, 2~ or 3~ or relevant part, see *() + 3~ [subsubsegment] * followed by text + text * followed by more text or 1~, 2~ or 3~ or relevant part, see *() + + * level A~ is the tile and is mandatory + * there can only be one level A~ + * heading levels BCD, are optional and there may be several of each + (where all three are used corresponding to e.g. Book Part Section) + * sublevels that are used must follow each other sequentially (alphabetically), + * heading levels A~ B~ C~ D~ are followed by other heading levels rather than substantive text + which may be the subsequent sequential (alphabetic) heading part level + or a heading (segment) level 1~ + * there must be at least one heading (segment) level 1~ + (the level on which the text is segmented, in a book would correspond to the Chapter level) + * additional heading levels 1~ 2~ 3~ are optional and there may be several of each + * heading levels 1~ 2~ 3~ are followed by text (which may be followed by the same heading level) + and/or the next lower numeric heading level (followed by text) + or indeed return to the relevant part level + (as a corollary to the rules above substantive text/ content + must be preceded by a level 1~ (2~ or 3~) heading) + +there must be a title, level A +creator field absent: crash, no warnings given +title missing: +level A missing: +no level 1: + +***** NOTES/COMMENTS + +revisit, + * check logic, add to if possible + * tidy, inelegant solution + +**** DONE (5.3.5::6.0.5) [#B] victory chals discussed parsing problem caused by use of open-close markers around url + + +*** DBT Outstanding bugs -- sisu caught by removal of ruby-dbi + +**** DONE (pending acceptance) [#B] sisu 5.3.4-1 marked for autoremoval from debian testing on 2014-06-10, for depending on ruby-dbi + +sisu 5.3.4-1 is marked for autoremoval from testing on 2014-06-10 +It (build-)depends on packages with these RC bugs: +746081: ruby-dbi: FTBFS: ERROR: Test "ruby2.1" failed: wrong number +of arguments (3 for 1..2) + +The current status of use of ruby-dbi in sisu. + +from: +http://lists.sisudoc.org/pipermail/sisu/2014-May/000818.html + +***** sisu + SiSU does not depend on an sql database to be useful and most users do + not use the database (population and resulting search) possibilities. + +***** DONE [#B] sisu-sqlite + 5.3.4 uses ruby-sqlite3 directly. There has been a + dependency within debian/control on ruby-dbi for sisu-sqlite, this can + safely be removed, without affecting its operation. + (it is used rather by the sample sqlite3 search form) + + >Solution Proposed: remove debian/control dependency on ruby-dbi + + Solution Implemented: + * sisu-sqlite uses 'sqlite3' ruby-sqlite3 (any superflous dbi loading dropped) + * code tests passed (create tables, populate db etc. work fine) + (closes) + +***** DONE [#B] sisu-postgresql + sisu-postgresql 5.3.4 uses ruby-pg through ruby-dbi. + + >Solution Proposed: + >* attempt now to fix by migrating to use ruby-pg directly + > * remove dependency on ruby-dbi in debian/control + > * rewrite code within sisu to work directly with ruby-pg + + Solution Implemented: + * sisu-postgresql uses 'pg' ruby-pg (ruby-dbi dropped) + * code tests passed (create tables, populate db etc. work fine) + (closes) + +***** DONE [#B] sample cgi search forms + there is a sample cgi search form facility within sisu that uses + ruby-dbi to query sqlite3 or pg databases. + + >Solution Proposed: + >* file a wishlist bug against sisu. No action needed immediately + > (other perhaps than to remove references to ruby-dbi). This offering + > in sisu would be classified as "wishlist" as these are samples only + > and need not be provided at all as populating the database (at an + > object level) in this case is the challenge (so you could say these + > documents meet your search criteria at these locations within them + > (relevant to almost all output formats html, epub, pdf etc.) (and + > may be looked up in these languages if they are available)) and is + > independent from search, once you have an sql database you can query + > it as you wish. (the cgi sample forms will be provided again + > eventually using ruby-sqlite3 and ruby-pg directly). + + Solution Implemented: + * sample cgi search froms (cgi database query forms) fixed :) + * pg sample uses 'pg' (dbi dropped) + generate sample form using: sisu --sample-search-form --db-pg + * sqlite sample uses 'sqlite3' (dbi dropped) + generate sample form using: sisu --sample-search-form --db-sqlite + (closes) + +***** NOTES/COMMENTS + +debian/control, remove dependency on ruby-dbi, contained in sisu-postgresql and sisu-sqlite + +Current status + * sisu-sqlite ok, uses 'sqlite3' (superflous dbi loading dropped) + * sisu-postgresql ok, uses 'pg' (dbi dropped) + * sample cgi search froms (cgi database query forms) ok :) + * pg sample uses 'pg' (dbi dropped) + * sqlite sample uses 'sqlite3' (dbi dropped) + +*** DBT Outstanding bugs -- Normal bugs; Unclassified (2 bugs) :debian:dbt:normal: + <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=sisu> + +**** DONE (5.3.5::6.0.5) [#B] #744360 [n|u] sisu: includes do not work properly :processing:fix: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744360> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: includes do not work properly +Date: Sun, 13 Apr 2014 12:38:59 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +using this in foo.ssm: + + :A~ foo + + :B~ bar + + << bar/baz.ssi + +and this in baz.ssi: + + 1~ foo bar baz + +then everything works. + +using the more natural foo.ssm: + + :A~ foo + + << bar/baz.ssi + +and baz.ssi: + + :B~ bar + + 1~ foo bar baz + +makes ':B~ bar' being ignored in the output (pdf) entirely. + +Regards, +Daniel + +***** NOTES/COMMENTS + +it appears both give faulty text, though in different ways + +fixed + +**** DONE (5.3.5::6.0.5) [#B] #744378 [n|u] sisu: --no-manifest not working anymore :check: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744378> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: --no-manifest not working anymore +Date: Sun, 13 Apr 2014 16:12:13 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when running sisu-pdf with --no-manifest, the output (pdf) still +contains the sisu manifest at the end of the document. + +Regards, +Daniel + +***** NOTES/COMMENTS + +fix, metadata page in pdf should not contain link to manifest where --no-manifest flag is used + + +**** DONE (5.3.5::6.0.5) [#D] #744353 [w|u] sisu output: please do not use typewriter for urls :output:consider: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744353> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: please do not use typewriter for urls +Date: Sun, 13 Apr 2014 12:28:27 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when using urls in sisu like this: + + http://example.org + +sisu then creates in the output (pdf) links like this: + + <http://example.org> + +where as '<http://example.org>' is written in typewriter font +(monospace). please don't do that automagically since it's desturbing +the visual flow when reading. If the users wants that, he should be able +to configure it. + +Regards, +Daniel + +***** NOTES/COMMENTS + +monospace for url outputs in pdf + +this is default behavior of the latex url package (it uses tt typewriter font) +it is possible to modify the font to sf class or tm/rm class, & I now default to sf +this means when the sisu default sf is used there will be no difference in typeface, +but when times roman or other is used, urls will be in sf instead of that font, +(instead of the latex default typewriter) + +it provides a visual cue even when output is monochrome, without color +(and is in some way related to #744391 sisu output: no color on a4 portrait) +however, it is worth noting here that urls are printed in a smaller font so as +to fit more on a line of text + +**** DONE (5.3.5::6.0.5) [#C] #744355 [w|u] vim syntaxhighlighting: includes and directories :syntaxhi:fix: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744355> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: vim syntaxhighlighting: includes and directories +Date: Sun, 13 Apr 2014 12:28:46 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +When using includes like this: + + << foo.ssi + +then vim correctly displays the line in blue. + +However, when using includes in a subdirectory like this: + + << bar/foo.ssi + +then vim doesn't use any colors at all. + +Regards, +Daniel + +***** NOTES/COMMENTS + +done + +**** DONE PASS [#C] #744356 [w|u] vim syntaxhighlighting: urls and tags :discuss:close: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744356> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: vim syntaxhighlighting: urls and tags +Date: Sun, 13 Apr 2014 12:28:56 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +When using an URL at the end of a sentence like this: + + Foo bar baz http://example.org. + +then vim properly highlights the url in blue. + +this also works properly when a second sentence after it, like: + + Foo bar baz http://example.org. Foo bar baz http://example.org. + +it works with html tag as well, like this: + + Foo bar baz http://example.org. <br />Foo bar baz http://example.org. + +but it doesn't work if there's no space: + + Foo bar baz http://example.org.<br />Foo bar baz http://example.org. + +then, the string 'http://www.gnu.org/licenses/.<' is shown red. + +Regards, +Daniel + +***** NOTES/COMMENTS + +this is meant to be flagged as an error, +(red indicates error, and is an error will not parse correctly) +even if the sisu parser works in the flagged case there is no promise that it will in future + +use of angle bracket markers (html markers) in sisu markup is depreciated. +for line-break use \\ instead, +for which there should be surrounding spaces or a preceding space and end of line; +if <br /> is still used there should be a space after the url - which sisu should remove in output. + +would like to close without further action +re-open if necessary + +**** DONE (6.0.5) [#C] #744357 [w|u] sisu output: please create mailto links automatically + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744357> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: please create mailto links automatically +Date: Sun, 13 Apr 2014 12:29:12 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +When using urls like: + + http://example.org + +in sisu, the output (pdf) contains a hyperlink to http://example.org +automatically, which is nice. + +please also create mailto links when using email adresses like: + + john.doe@example.org + +Regards, +Daniel + +***** NOTES/COMMENTS + +for pdf fix/implement mailto links +done but requires further testing & possibly refinement + +**** DONE (5.3.5::6.0.5) [#C] #744358 [w|u] sisu output: please do not add ';' after \:copyright: :output:fix: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744358> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: please do not add ';' after :copyright: +Date: Sun, 13 Apr 2014 12:29:20 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +When using: + + :copyright: foo bar baz. + +sisu generates the following in the output format (pdf): + + foo bar baz.; + +Please do not automagically add a semicolon (;). If the user wants a +semicolon, he would add one. + +Regards, +Daniel + +***** NOTES/COMMENTS + +fix copyright, remove trailing semi-colon + +**** DONE (5.3.5::6.0.5) [#B] #744379 [w|u] sisu: missing includes doesn't give an error :processing:fix: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744379> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: missing includes doesn't give an error +Date: Sun, 13 Apr 2014 16:14:46 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +When using includes (*.ssi) in a sisu master document (*.ssm) like: + + << foo.ssi + +and that to be included file foo.ssi (for whatever reason) doesn't +exist, sisu doesn't error out but include '<< foo.ssi' literally as a +string in the output (pdf). + +Regards, +Daniel + +***** NOTES/COMMENTS + +5.3.4-1 writes the following to the screen: +"ERROR test.ssm.sst requires invalid or non-existent file: foo.ssi" + +and unsatisfactorily within the text output it writes no error message but the include instruction: + +"<< foo.ssi" + +5.3.5, the current "fix"/ solution, is to add an error message within the text rather than to stop processing with an error. +In addition to (i) slightly modified (you could say corrected) to the following: + +"ERROR test.ssm requires an invalid or non-existent file: foo.ssi" + +the following is written within the text output: + +"<< foo.ssi [ERROR test.ssm requires an invalid or non-existent file: foo.ssi]" + +**** DONE (5.3.5::6.0.5) [#D] #744381 [w|u] sisu syntax: inconsistency \:copyright: and \:license: :metadata: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744381https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744381> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: inconsistency between :copyright: and :license: +Date: Sun, 13 Apr 2014 16:26:55 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when using ':copyright: foo', then the output contains 'foo'. + +when using ':license: foo', then the output contains 'License: foo'. + +this is inconsistent. either both should have a 'prefix' in the output, +or neither should have one (i'd prefere the latter). + +Regards, +Daniel + +***** NOTES/COMMENTS + +Under rights there are a series of sub-categories starting with copyright, that +need to be distinguished. Until now started distinguishing after after +Copyright. For consistency have add the prefix 'Copyright' to the output. +Preference to omit noted, but this solution is consistent with options +provided. Bug closed, re-open if necessary. + +**** DONE (6.0.5) [#B] #744383 [w|u] sisu syntax: :B and :C result in the same formatting :output:fix: (partial solution) + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744383> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu syntax: :B and :C result in the same formatting +Date: Sun, 13 Apr 2014 16:32:07 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +when using :A, :B, and :C in sisu, in the output (pdf) both :B and :C +are formatted identically. + +imho :C should be 'smaller' than :B. + +or, as an analogy with html: i would expect that :A equals <h1>, :B +equals <h2>, and :C equals <h3>. currently, (in that analogy), :B and :C +both equal <h2>. + +Regards, +Daniel + +***** NOTES/COMMENTS + +this is in part an artifact of LaTeX not having as many document heading levels +and trying to take advantage of the behavior of existing levels rather than +customizing further + +look for a solution, possibly overriding the default font sizes for each + +The current settings were chosen because, there are not enough levels and I +find too many different font sizes disconcerting, especially running sisu over +a wide variety of document types + +the following levels are available in LaTeX + +\part +\chapter +\section +\subsection +\subsubsection + +the levels in sisu are + +A [title] +B [part] +C [subpart] +D [subsubpart] +1 [segment (chapter)] +2 [subsegment] +3 [subsubsegment] + +sisu current mapping: + +level A [title] +level B C D \part (it is up to the user to make part levels visually distinguishable e.g. Book Part Section) +[skipped \chapter] +[skipped \section] +level 1 \subsection +level 2 \subsubsection +level 3 \subsubsection + +the reason for skipping section was the default configuration and resulting +fact that it made for a table of contents that takes more space + +sisu new mapping: + +level A [title] +level B C D \part (it is up to the user to make part levels visually distinguishable e.g. Book Part Section) +[skipped \chapter] +level 1 \section +level 2 \subsection +level 3 \subsubsection + +levels B C & D are the same size, + it is up to the user to make part levels visually distinguishable + e.g. Book Part Section +levels 1 2 & 3 are now distinguished + +(Closes #744386) sisu syntax: 1~ and 2~ result in the same formatting +(under consideration & yet to be done #744383) sisu syntax: :B and :C result in the same formatting +(touches ) +override part font size settings for different levels (B C D) + +**** DONE CLOSED [#C] #744384 [w|u] sisu syntax: relies on empty lines + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744384> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu syntax: relies on empty lines +Date: Sun, 13 Apr 2014 16:34:46 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +the following snipped: + + :C~ foo bar + << foo-bar.ssi + +means that the include is ignored entirely. apparently sisu relies on +having an empty line in between like this: + + :C~ foo bar + + << foo-bar.ssi + +Regards, +Daniel + +***** NOTES/COMMENTS + +consider, + +(i) as a general observation, sisu relies on emptly lines to identify separate objects + such as headings, paragraphs (and indeed insertions) + +(ii) a heading need not be on a single line (so << would be part of that heading) +this means sisu should be able to work identifying headings in wrapped texts +(e.g. where the text is wrapped at 80 and the heading is longer than that) + +there has been no rule to the contrary (i.e. that headings should be on a single text line) + +consider, should there be such a rule? + +**** DONE (5.3.5::6.0.5) [#B] #744386 [w|u] sisu syntax: 1~ and 2~ result in the same formatting :output:pdf:fix: (see #744383) + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744386> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu syntax: 1~ and 2~ result in the same formatting +Date: Sun, 13 Apr 2014 16:43:51 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist + +similar as with #744383, the same also applies for 1~ and 2~ - they +should be different in the output format (pdf here). + +Regards, +Daniel + +***** NOTES/COMMENTS + +1~ 2~ 3~ are now differentiated + +deal with under #744383 + +**** DONE (5.3.5::6.0.5) [#C] #744391 [w|u] sisu output: no color on a4 portrait :output:pdf:contemplate: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744391> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu output: please use (blue) color for links +Date: Sun, 13 Apr 2014 17:23:37 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +it would be nice if links (urls and emails) would be colored blue to +mark them visually as links. this behaviour is somewhat the lowest +common denominator in browsers (if you use html without any css that is). + +Regards, +Daniel + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: 744391@bugs.debian.org +Subject: Re: sisu output: please use (blue) color for links +Date: Sun, 13 Apr 2014 17:35:33 +0200 +retitle 744391 sisu output: no color on a4 portrait +thanks + +now this is strange.. turns out that (yes, i have colors enabled in +sisurc) the portrait a4 pdf has no colors at all, while the landscape a4 +pdf does indeed have colors (red for toc, blue for links). + +Regards, +Daniel + +***** NOTES/COMMENTS + +background: +portrait was provided for print/paper copy and is great for that in monochrome +(without grays for colored links), +landscape better matching a screen for visual presentations, color affecting the landscape only + +solution: +make configurable by cli & rc file +make both (portrait & landscape colors) configurable +either as hyperlinks monochrome or colored +overriding existing default which remains as described + +document +cli: +--pdf-hyperlinks-no-color or --pdf-hyperlinks-mono +--pdf-hyperlinks-color + +rc: + +default: + pdf_hyperlinks: *[possible values] + pdf_hyperlinks_portrait: *[possible values] + pdf_hyperlinks_landscape: *[possible values] + + * 'color' or ('mono' or 'no-color' or 'color-off') + + +**** DONE (5.3.5::6.0.5) [#B] #744399 [w|u] sisu syntax: :A smaller formatted than :B :output:fix: (see #744383) (partial solution) + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744399> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu syntax: :A smaller formatted than :B +Date: Sun, 13 Apr 2014 17:49:26 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +in a document like this: + +:A~ foo + +:B~ bar + +the :A~ 'title' is formated 'smaller' (not bold, smaller font size) than +the :B~ 'title' on the first page of the actual document (means, first +page after TOC). + +Regards, +Daniel + +***** NOTES/COMMENTS + +for pdf + +now is same size see #744383 + +\part (level A B C D) +\chapter (skipped) +\section (level 1) +\subsection (level 2) +\subsubsection (level 3) + +**** DONE (5.3.5::6.0.5) [#C] #744402 [w|u] sisu: support sha512 :implement: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744402> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu: support sha512 +Date: Sun, 13 Apr 2014 18:06:56 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +sisu uses sha256 when using sha as digest, please support sha512. + +it would be even nicer if you could specify the actual digest like +'sha512', 'sha256', etc. rather than just 'sha'. + +Regards, +Daniel + +***** NOTES/COMMENTS + +implemented +document command line option --sha512 + +**** DONE (5.3.5::6.0.5) [#C] #744405 [w|u] sisu: set default font size :configuration:pdf:implement: + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744405> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu: set default font size +Date: Sun, 13 Apr 2014 18:29:46 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +in sisurc, one can set the default fonts. it would be nice to be also +able to set the default font size. + +Regards, +Daniel + +***** NOTES/COMMENTS + +for pdf make configurable + +yaml.rc + +default: + texpdf_fontsize: 12 + +command-line + +--pdf-fontsize-12 +--pdf-fontsize-8 +etc. + + +**** DONE (5.5.0::6.1.0) [#C] #744408 [w|u] sisu: support more than one level of includes/nested includes + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744408> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu: support more than one level of includes/nested includes +Date: Sun, 13 Apr 2014 18:39:23 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +currently, it's possible to use only one ssm file which itself includes +one or more ssi files. + +it would be nice if the ssm could include an 'intermediate' ssi, which +then includes further ssi files. this is very handy for larger documents. + +Regards, +Daniel + +***** NOTES/COMMENTS + +consider, +I have to date deliberately tried to keep it easy to follow documents & not have too much depth ... +The idea of recursive includes is un-attractive (messy for a document) + +.ssm currently can contain/include .sst or .ssi +.sst files can be processed independently, +.ssi files are only insertions & are not processed independently but as part of an ssm + +change proposed +.ssm unchanged +.sst unchanged +.ssi as before, but can include .sst or .ssi, so: + files are only insertions & are not processed independently but as part of an .ssm or another .ssi + i.e. as before with the addition that it like a .ssm can contain/include .sst or .ssi + +this is pretty much as requested by wishlist 744408 + +allowing .ssi to also include other .ssi or .sst could lead to recursive .ssi + +stopping after an additional level of includes seems arbitrary, and possibly prone to error if you are dealing with many documents + +**** DONE (6.0.5) [#C] #744541 [w|u] sisu: urls in @creator broken + <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744541> + +From: Daniel Baumann <daniel.baumann@progress-technologies.net> +To: Debian Bug Tracking System <submit@bugs.debian.org> +Subject: sisu: urls in @creator broken +Date: Sun, 13 Apr 2014 18:45:35 +0200 +Package: sisu +Version: 5.3.4-1 +Severity: wishlist +Tags: upstream + +first, if you have an url within @creator, like: + + @creator: foo bar http://example.org + +the generation fails (pdf output). + +as a workaround, i put the url into parenthesis, like: + + @creator: foo bar (http://example.org) + +but then, it would be nice if that url would be automatically +transformed into a link in the output format (pdf). + +Regards, +Daniel + +***** NOTES/COMMENTS + +pdf, fix diff --git a/data/doc/sisu/org/in_progress/sisu_asciidoc.org b/data/doc/sisu/org/in_progress/sisu_asciidoc.org new file mode 100644 index 00000000..bd2ec738 --- /dev/null +++ b/data/doc/sisu/org/in_progress/sisu_asciidoc.org @@ -0,0 +1,140 @@ +***** urls +#% asciidoc +<http://asciidoc.org/> +<http://asciidoctor.org/> +<http://www.methods.co.nz/asciidoc/> +<http://en.wikipedia.org/wiki/AsciiDoc> + +cheatsheets +<http://powerman.name/doc/asciidoc> +<http://powerman.name/doc/asciidoc-index> + +<http://www.methods.co.nz/asciidoc/asciidoc.txt> +<http://www.methods.co.nz/asciidoc/userguide.html> + +<http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html> +<http://www.methods.co.nz/asciidoc/asciidoc.html> +<http://www.methods.co.nz/asciidoc/chunked/index.html> + +***** rb file +lib/sisu/v6/txt_asaciidoc.rb + +***** transformations :transformations:markup_asciidoc: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-4) (decoration) + [] inline + '== ' + '=== ' + '==== ' + '===== ' + '' + '' + [] underscore + '-' + '~' + '^' + '+' + '' ['.' proposed] + '' ['.' proposed] + [] node (child, parent ...) + +#% font face + [open & close marks] + [] bold + '*' + [] italics + '_' + [] underscore + '' + [] superscript + '^' + [] subscript + '~' + [] strike + '-' + [] add + [] monospace + '+' + '`' pass markup through unchanged, monospace code + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + [levels 1-6] + '*' + '**' + '***' + '****' + '*****' + '*******' + [] numbered list + [levels 1-3] + '. ' number + '.. ' lower alpha + '... ' lower roman + '.... ' upper alpha + '..... ' upper roman + +#% blocks + [] code + [source,perl] + ---- + code here + ---- + [] [type of markup if any] + [] poem + [] group + ---- + grouped text here, actually a listing block + ---- + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + http://google.com[Google Search] + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + "+\n" + forced + + line break + [] horizontal rule + [] column break + [] page break + +#% comment + [] comment + // + +#% misc + + [] term & definition +Term 1:: Definition 1 +Term 2:: Definition 2 +[horizontal] + Term 2.1;; + Definition 2.1 + Term 2.2;; + Definition 2.2 + diff --git a/data/doc/sisu/org/in_progress/sisu_docbook.org b/data/doc/sisu/org/in_progress/sisu_docbook.org new file mode 100644 index 00000000..7b1ac29b --- /dev/null +++ b/data/doc/sisu/org/in_progress/sisu_docbook.org @@ -0,0 +1,77 @@ +***** urls +#% docbook book xml.txt +<http://www.docbook.org> +<http://www.sagehill.net/docbookxsl/index.html> +<http://wiki.docbook.org/> +<http://www.docbook.org/tdg5/en/html/> +<http://www.docbook.org/tdg5/en/html/docbook.html> +<http://www.docbook.org/tdg5/en/html/ch01.html> +<http://www.docbook.org/tdg5/en/html/ch02.html> +<http://www.sagehill.net/docbookxsl/index.html> + +<http://www.docbook.org/schemas/5x> +<http://www.docbook.org/xml/5.0/> + +<http://infohost.nmt.edu/tcc/help/pubs/docbook5/web/index.html> + +<http://docbook.org/xml/5.0/rng/docbook.rng> +<http://docbook.org/xml/5.0/rng/docbook.rnc> + +<http://www.cuddletech.com/blog/pivot/entry.php?id=509> + +***** rb file +lib/sisu/v6/xml_docbook5.rb + +***** transformations :transform:markup_docbook: +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [] node (child, parent ...) + +#% font face + [] bold + [] italics + [] underscore + [] superscript + [] subscript + [] strike + [] add + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + +#% blocks + <http://www.docbook.org/tdg5/en/html/literallayout.html> + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + <http://www.docbook.org/tdg5/en/html/toc.html> + [] index (book index) + +#% misc + diff --git a/data/doc/sisu/org/in_progress/sisu_fictionbook.org b/data/doc/sisu/org/in_progress/sisu_fictionbook.org new file mode 100644 index 00000000..f689c30a --- /dev/null +++ b/data/doc/sisu/org/in_progress/sisu_fictionbook.org @@ -0,0 +1,86 @@ + +<http://en.wikipedia.org/wiki/FictionBook> +<http://fictionbook.org/index.php/Eng:FictionBook> +<http://fictionbook.org/index.php/Eng:Articles> +<http://fictionbook.org/index.php/Eng:Documentations> +<http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1> +<http://www.fictionbook.org/index.php/Eng:FictionBook> +<http://fictionbook-lib.org/> +<http://fictionbook-lib.org/browse.php> +<http://wiki.mobileread.com/wiki/FB2> + +***** rb file +lib/sisu/v6/xml_fictionbook2.rb + +***** transformations :transformations:markup_fictionbok: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [] node (child, parent ...) + +#% font face + [] bold + [] italics + [] underscore + [] superscript + [] subscript + [] strike + [] add + [] monospace + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + +#% blocks + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + [] column break + [] page break + +#% comment + [] comment + +#% misc + +<http://en.wikipedia.org/wiki/FictionBook> +<http://fictionbook.org/index.php/Eng:FictionBook> +<http://fictionbook.org/index.php/Eng:Articles> +<http://fictionbook.org/index.php/Eng:Documentations> +<http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1> +<http://www.fictionbook.org/index.php/Eng:FictionBook> + +<http://www.fictionbook.org/index.php/%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0_%D0%B2_FB2> + +<https://addons.mozilla.org/en-US/firefox/addon/fb2-reader/> + diff --git a/data/doc/sisu/org/in_progress/sisu_markdown.org b/data/doc/sisu/org/in_progress/sisu_markdown.org new file mode 100644 index 00000000..0171f236 --- /dev/null +++ b/data/doc/sisu/org/in_progress/sisu_markdown.org @@ -0,0 +1,139 @@ + +***** urls + +#% markdown +<http://daringfireball.net/projects/markdown/> +<http://daringfireball.net/projects/markdown/syntax> +<http://daringfireball.net/projects/markdown/basics> +<http://en.wikipedia.org/wiki/Markdown> +<https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> +<http://whatismarkdown.com/> + +Markdown supports two styles of headers, Setext and atx +Setext +<http://docutils.sourceforge.net/mirror/setext.html> +<http://en.wikipedia.org/wiki/Setext> +atx +<http://www.aaronsw.com/2002/atx/intro> + +<http://support.iawriter.com/help/kb/general-questions/markdown-syntax-reference-guide> +<http://bywordapp.com/markdown/syntax.html> +<http://stackoverflow.com/editing-help> + +<http://support.mashery.com/docs/customizing_your_portal/Markdown_Cheat_Sheet> +<http://warpedvisions.org/projects/markdown-cheat-sheet.md> +<http://nestacms.com/docs/creating-content/markdown-cheat-sheet> +<https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> + +<https://help.github.com/articles/github-flavored-markdown> +<http://lifehacker.com/5943320/what-is-markdown-and-why-is-it-better-for-my-to+do-lists-and-notes> + +#% pandoc markdown +<http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html> +<http://johnmacfarlane.net/pandoc/README.html> +<http://johnmacfarlane.net/pandoc/demo/example19/Pandoc_0027s-markdown.html> +<http://johnmacfarlane.net/pandoc/> +<http://johnmacfarlane.net/pandoc/epub.html> +<http://johnmacfarlane.net/pandoc/faqs.html> + +#% multimarkdown +<http://fletcher.github.io/peg-multimarkdown/> + +#% markdown pandoc v multimarkdown +<https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown> + +#% rST v markdown +<http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext> + +***** rb file +lib/sisu/v6/txt_markdown.rb + +***** transformations :transformations:markup_markdown: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [inline 1-5] + '#' + '##' + '###' + '####' + '#####' + '######' + [underscore 1-5] + '=' + '-' + #'~' + #'^' + #'+' + [] node (child, parent ...) + +#% font face + [open & close marks] + [] bold + '**' + [] italics + '*' + [] underscore + '' + [] superscript + '' + [] subscript + '' + [] strike + '' + [] add + [] monospace + '`' + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + '*' + [] numbered list + '0.' + +#% blocks + [] code + ' ' #indent at least 4 spaces + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [] [bibliography?] + +#% links, linking + [] links - external, web, url + [] links - internal + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + (three or more asterisks hypens or underscores) + * * * + *** + ***** + - - - + ___ + [] column break + [] page break + +#% misc + diff --git a/data/doc/sisu/org/in_progress/sisu_rst.org b/data/doc/sisu/org/in_progress/sisu_rst.org new file mode 100644 index 00000000..27a8ec25 --- /dev/null +++ b/data/doc/sisu/org/in_progress/sisu_rst.org @@ -0,0 +1,236 @@ + +***** urls +#% rST +<http://docutils.sourceforge.net/rst.html> +<http://docutils.sourceforge.net/docs/user/rst/quickref.html> +<http://docutils.sourceforge.net/docs/user/rst/quickstart.html> +<http://en.wikipedia.org/wiki/ReStructuredText> +<http://sphinx-doc.org/rest.html> + +<http://stackoverflow.com/questions/2746692/restructuredtext-tool-support> + +#% rST v markdown +<http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext> + +***** rb file +lib/sisu/v6/txt_rst.rb + +***** transformations :transformations:markup_rst: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [inline] + N/A + [underscore] + Titles are underlined (or over- and underlined) with a printing + nonalphanumeric 7-bit ASCII character. Recommended choices are + "= - ` : ' " ~ ^ _ * + # < >". The underline/overline must be at + least as long as the title text. + '=' + '-' + '`' + ':' + "'" + '"' + + [] node (child, parent ...) + +#% font face + [] bold + '**' + [] italics + '*' + [] underscore + '+' + [] superscript + '^' + [] subscript + [] strike + '-' + [] add + [] monospace + '``' + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + "-", "*" or "+" + '-' + [] numbered list + '#.' + +#% blocks + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + +#% notes + [] footnotes + [binary] + Footnote references, like [5]_. + Note that footnotes may get + rearranged, e.g., to the bottom of + the "page". + .. [5] A numerical footnote. + -- + Autonumbered footnotes are + possible, like using [#]_ and [#]_. + .. [#] This is the first one. + .. [#] This is the second one. + + [] [bibliography?] + +#% links, linking + [] links - external, web, url + Typical result + External hyperlinks, like Python_. + .. _Python: <http://www.python.org/> + or + External hyperlinks, like `Python + <http://www.python.org/>`_. + [] links - internal + Internal crossreferences, like example_. + .. _example: + + This is an example crossreference target. + -- + Titles are targets, too + ======================= + Implict references, like `Titles are + targets, too`_. + +#% images [multimedia?] + [] images + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + [] column break + [] page break + +#% misc + +**** TODO [#F] textile :feature: + +***** urls +#% textile +<http://en.wikipedia.org/wiki/Textile_(markup_language)> +v2.4 +<http://www.txstyle.org/> +v2 +<http://redcloth.org/hobix.com/textile/> + +***** rb file +lib/sisu/v6/txt_textile.rb + +***** transformations :transformations:markup_textile: #% +#% structure - headings, levels + [] sisu (A-C, 1-3) + [] collapsed (1-6) (decoration) + [inline] + h1(#id). An HTML first-level heading + h2. An HTML second-level heading + h3. An HTML third-level heading + h4. An HTML fourth-level heading + h5. An HTML fifth-level heading + h6. An HTML sixth-level heading + [underscore] + N/A + + [] node (child, parent ...) + +#% font face + [] bold + *bold text* + [] italics + _italic text_ + [] underscore + +underlined text+ + [] superscript + ^TM^ + [] subscript + ~subscript~ + [] strike + -strikethrough text- + [] add + +#% para + [] default + [] indent + [] default, all + [] first line hang or indent further + [] bullet + * bulleted list + ** 2-level + +#% blocks + [] code + [] [type of markup if any] + [] poem + [] group + [] alt + [] tables + |Table | with two columns | + |and two | rows | + +#% notes + [] footnotes + Text with a link to some reference[1] + fn1. Footnote explanation + [] [bibliography?] + +#% links, linking + [] links - external, web, url + "(classname)link text(title tooltip)":link_address + "Link to Wikipedia":http://www.wikipedia.org + [] links - internal + +#% images [multimedia?] + [] images + !http://commons.wikimedia.org/wiki/Special:Filepath/Wikipedia-logo-en.png! + !imageurl(alt text)! + [] [base 64] + +#% object numbers + [] ocn (object numbers) + +#% contents + [] toc (table of contents) + [] index (book index) + +#% breaks + [] line break + [] horizontal rule + [] column break + [] page break + +#% misc + [] *_bold italic text_* + [] *-bold strikethrough text-* + [] *_-bold italic strikethrough text-_* + [] *+bold underlined text+* + [] *_+italic underlined text+_ + [] *_+bold italic underlined text+_ + [] *_-+bold italic strikethrough underlined text+-_* + %{font-size:18pt}font size% + %{color:red}text in red% + # Chapter 1 + +#% notes +heading inline only +footnotes uses marker and endnote, check + diff --git a/data/doc/sisu/org/in_progress/sisu_todo.org b/data/doc/sisu/org/in_progress/sisu_todo.org new file mode 100644 index 00000000..2bec4987 --- /dev/null +++ b/data/doc/sisu/org/in_progress/sisu_todo.org @@ -0,0 +1,192 @@ +* things i want +- vim style folds (setup like my .org mode like folds) working in both + - vim + - emacs +- elastic search +- outputs + - docbook + - asciidoc +- odt to sisu form? +- description of the focus of sisu as a smarttext, compared to + - asciidoc --> docbook; + - markdown --> natural writing, visually meaningful + - sisu --> identify document structure & objects +* proposals/additions + +** TODO [#B] markup indicate objects language where other than document default +at end of text object mark language from language code list (SiSU_is[:language_list_regex]) ~:ja + +to mark subsequent objects as being of a particular language ^:~(SiSU_is[:language_list_regex])$ +:~ja +to return to language default ^:~-$ +:~- +** TODO [#B] markup syntax code block, indicate syntax of code block :feature: +``` code:ruby + +** TODO [#C] colored boxes round text :feature:ponder: + ``` box:red (select color of box) + ``` box:warn ``` box:tip (some default boxes? decide) + ``` box:red:"Warn" (select color and lead text of box, else instead + select color box & use regular single line bold markup ^!_ Warn$) + +** TODO [#D] blockquotes implement? :feature:ponder: + ``` quote + not sure how best to represent + +** TODO [#D] bibliography :feature:ponder: + +** TODO speaker, as e.g. play (irc?) :feature:ponder: + ``` Ophelia: + ::Ophelia + +** TODO [#F] time stamp (e.g. for irc, video text?):feature:ponder: + ``` 04:03 + ``` 04:03 ... 07:12 + ``` 04:03 + 03:09 + ``` 12:04:03 + ``` 12:04:03 ... 12:07:12 + ``` 12:04:03 + 03:09 + probably not worth the effort, as time stamp is an alternative + identifying number (to ocn, and ∴ sisu objects not ideal) + +** TODO book index, alternative based on search within text + + +* Document Abstraction :sisu:doc_abstr: + +** TODO [#D] XML middle layer? + +*** XMLda sisu + consder alternative sisu layer in XML + +*** TODO [#D] RelaxNG sisu + +* Output :sisu:output: + +** New outputs to consider +*** elasticsearch +*** JSON for elasticsearch +*** XML :xml: +%% xml, docbook.txt fictionbook.txt xldl.txt lml.txt tei.txt emacs.txt +<http://xml.silmaril.ie/> +<http://www.xml.com/> +<http://programming.oreilly.com/2012/08/shrinking-and-stretching-the-boundaries-of-markup.htmlhttp://programming.oreilly.com/2012/08/shrinking-and-stretching-the-boundaries-of-markup.html> + +<http://broadcast.oreilly.com/2012/03/xmls-dialect-problem.html> + +xml editor vim emacs +<http://chimera.labs.oreilly.com/books/1234000000058/ch01.html#which_xml_editor_should_i_use> +nXML plugin +<http://blog.tommorris.org/post/2456183251/emacs-and-nxml-survival-guide> +<http://johnbokma.com/mexit/2008/10/01/nxml-emacs-how-to.html> +<http://www.emacswiki.org/cgi-bin/wiki/NxmlModeForXHTML> +<http://www.xmlhack.com/read.php_item=2061> +<http://infohost.nmt.edu/tcc/help/pubs/nxml/index.html> +emacs.txt evil.txt + +<http://www.oreillynet.com/xml/blog/2005/10/smart_quotes_and_more_in_vim_a.html> +<http://stackoverflow.com/questions/1430164/differences-between-emacs-and-vim> + +To validate a book.xml file using xmllint, run the following command: +$ xmllint --postvalid --xinclude --noout book.xml + +The default location where xmllint will look for the catalog file is +/etc/xml/catalog. Alternatively, you can set the environment variable +XML_CATALOG_FILES to define another default location for catalog +files. Once you’ve got the DTD and catalog set up locally, you can +validate as before: +$ xmllint --postvalid --xinclude --noout book.xml + +%% Docbook +sisu_docbook.org + +%% Fictionbook +sisu_fictionbook.org + +%% XLDL +xldl.txt + +%% Literature Markup Language +lml.txt + +%% Text Encoding Initiative +tei.txt + +**** TODO [#B] docbook :feature: +sisu_docbook.org + +**** TODO [#D] fictionbook :feature: + +***** urls + +**** TODO [#B] fictionbook :feature: +sisu_fictionbook.org + +**** TODO [#D] XLDL :feature: + +***** urls +%% xml.txt xldl - novels, stories, poems +Name: XLDL - an XML doctype for novels, stories, poems, playsName: XLDL - an XML doctype for novels, stories, poems, plays +<http://www.ister.org/code/xldl/> +<http://www.ister.org/code/xldl/doc/xldl.dtd.html> +<line> <stanza> + +**** TODO [#E] Literature Markup Language - <LML /> :feature: + +***** urls +%% Literature Markup Language - <LML /> +<http://hoffmann.bplaced.net/lml/> +"It is assumed, that there are three quite different techniques to provide text, +respectively three types of text, this is prose and poetry and code (for +example source code of computer programs or from markup languages)." +Suggestions and Ideas for Literature Markup Language - <LML /> 1.1 +<http://hoffmann.bplaced.net/lml/lml1.1.php> + +**** TODO [#E] TEI Lite (Text Encoding Initiative) :feature: + +***** urls +%% TEI Lite (Text Encoding Initiative) +<http://www.tei-c.org/Guidelines/Customization/Lite/> +<http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_lite.doc.html> + +*** Text :txt: + +sisu_markup.txt asciidoc.txt markdown.txt textile.txt rst.txt + +**** TODO [#D] asciidoc :feature: +sisu_asciidoc.org + +**** TODO [#E] markdown :feature: +sisu_markdown.org + +**** TODO [#F] rst :feature: +sisu_rst.org + +** Improvements + +*** HTML + +*** XML + +*** --strict mode (html w3c compliant ocn etc.) + +* Code (ruby) :sisu:code: + +** code enhancements :enhance: + +*** TODO [#D] directory & path, use ruby directory tools + +*** TODO [#D] document url shortcut, allow addition of alternative dir stub +(e.g. viral Spiral) + +** code refactoring :refactor: + +*** ruby 2.1 + +*** TODO [#C] refactor ruby :ongoing: + +* Reference versions +** v5 +5.6.2 +5.6.1 +5.5.6 (5.5.5) diff --git a/data/doc/sisu/org/sisu.org b/data/doc/sisu/org/sisu.org new file mode 100644 index 00000000..fdcb3eaa --- /dev/null +++ b/data/doc/sisu/org/sisu.org @@ -0,0 +1,853 @@ +#+PRIORITIES: A F E +#+OPTIONS: ^:nil _:nil +(emacs:evil mode gifts a "vim" of enticing "alternative" powers! ;) +(vim, my _editor_ of choice also in the emacs environment :) + +* What is SiSU? + +Multiple output formats with a nod to the strengths of each output format and +the ability to cite text easily across output formats. + +** debian/control desc + +documents - structuring, publishing in multiple formats and search + SiSU is a lightweight markup based, command line oriented, document + structuring, publishing and search, static content tool for document + collections. + . + With minimal preparation of a plain-text (UTF-8) file, using sisu markup syntax + in your text editor of choice, SiSU can generate various document formats, most + of which share a common object numbering system for locating content, including + plain text, HTML, XHTML, XML, EPUB, OpenDocument text (ODF:ODT), LaTeX, PDF + files, and populate an SQL database with objects (roughly paragraph-sized + chunks) so searches may be performed and matches returned with that degree of + granularity. Think of being able to finely match text in documents, using + common object numbers, across different output formats and across languages if + you have translations of the same document. For search, your criteria is met + by these documents at these locations within each document (equally relevant + across different output formats and languages). To be clear (if obvious) page + numbers provide none of this functionality. Object numbering is particularly + suitable for "published" works (finalized texts as opposed to works that are + frequently changed or updated) for which it provides a fixed means of reference + of content. Document outputs can also share provided semantic meta-data. + . + SiSU also provides concordance files, document content certificates and + manifests of generated output and the means to make book indexes that make use + of its object numbering. + . + Syntax highlighting and folding (outlining) files are provided for the Vim and + Emacs editors. + . + Dependencies for various features are taken care of in sisu related packages. + The package sisu-complete installs the whole of SiSU. + . + Additional document markup samples are provided in the package + sisu-markup-samples which is found in the non-free archive. The licenses for + the substantive content of the marked up documents provided is that provided + by the author or original publisher. + . + SiSU uses utf-8 & parses left to right. Currently supported languages: + am bg bn br ca cs cy da de el en eo es et eu fi fr ga gl he hi hr hy ia is it + ja ko la lo lt lv ml mr nl nn no oc pl pt pt_BR ro ru sa se sk sl sq sr sv ta + te th tk tr uk ur us vi zh (see XeTeX polyglossia & cjk) + . + SiSU works well under po4a translation management, for which an administrative + sample Rakefile is provided with sisu_manual under markup-samples. + +** take two + +SiSU may be regarded as an open access document publishing platform, applicable +to a modest but substantial domain of documents (typically law and literature, +but also some forms of technical writing), that is tasked to address certain +challenges I identified as being of interest to me over the years in open +publishing. + +The idea and implementation may be of interest to consider as some of the +issues encountered and that it seeks to address are known and common to such +endeavors. Amongst them: + + * how do you ensure what you do now can be read in decades? + * how do you keep up with new changing and technologies? + * do you select a canonical format to represent your documents, if so + what? + * how do you reliably cite (locate) material in different document + representations? + * how do you deal with multilingual texts? + * what of search? + * how are documents contributed to the collection? + +(these questions are selected in to help describe the direction of efforts with +regard to sisu). + +My Dabblings in the Domain of Open Publishing +--------------------------------------------- + +The system is called SiSU, it is an offshoot of my early efforts at finding out +what to make of the web, that started at the University of Tromsø in 1993 (an +early law website Ananse/ International Trade Law Project / Lex Mercatoria). I +have worked on SiSU continually since 1997 and it has been open source in 2005 +(under a license called GPL3+), though I remain its developer. + +In working in this field I have had to address some of the common issues. + +So how do you ensure what you do now can be read in decades to come? There are +alternative solutions. (i) stick with a widely used and not overly complicated +well document open standard, and for that the likes of odf is an excellent +choice (ii) alternatively go for the most basic representation of a document +that meets your needs, in my case based on UTF-8 text and some markup tags, +fairly easily parsable by the human eye and as long as utf8 is in use it will +always be possible to extract the information + +How do you keep up with new changing and technologies? Here my solution has +been to generate new versions of the substantive content so as to always have +the latest document representations available e.g. HTML has changed a lot over +the years, different specifications come out for various formats including ODF, +electronic readers have become an important viewing alternative, introducing +the open reader format EPUB. Output representations are generated from source +documents. Different open document file formats can be produced and databases +and search engines populated. (The source documents and interpreter are all +that are required to re-create site content. Source documents can be made +public or retained privately). The strict separation of a simple source +document from the output produced, means that with updates to SiSU (the +interpreter/processor/generator), outputs can be updated technically as +necessary, and new output formats added when needed. Amongst the output formats +currently supported are HTML, LaTeX generated Pdfs (A4, letter, other; +landscape, portrait), Epub, Open Document Format text. Returning to HTML as an +example, it has changed a lot over the years I have worked with it, this way of +working has meant it is possible to keep producing current versions of HTML, +retaining the original substantive document... and new formats have been added +as thought desired. There is no attempt to make output in different document +formats/ representations look alike let alone identical. Rather the attempt is +to optimize output for the particular document filetype, (there is no reason +why an epub document would look or behave like an open document text or that a +Pdf would look like HTML output; rather PDF is optimized for paper viewing, +HTML for screen etc.) Wherever possible features associated with the +particular output type are taken advantage of. This freedom is made possible to +a large extent by the answer to the question that follows. + +How do you reliably cite (locate) material in different document +representations? The traditional answer has been to have a canonical +publication, and resulting fixed page numbers. This was not a viable solution +for HTML (which changes from one viewer to another and with selectable font +faces & size etc.); nor is it otherwise ideal in an electronic age with the +possibility of presenting/interacting with material/documents in so many +different ways. Why be so restricted? Here my solution has been "object +citation numbering". What the various generated document formats have in +common is a shared object numbering system that identifies the location of text +and that is available for citation purposes. Object numbers are: sequential +numbers assigned to each identified object in a document. Objects are logical +units of text (or equivalent parts of a document), usually paragraphs, but also +document headings, tables, images, in a poem a verse etc. [In an electronic +publishing age are page numbers the best we can come up with? Change font +type, font size, page orientation, paper size (sometimes even the viewer) and +where are you with them? And paper though a favorite medium of mine is no +longer the sole (or sometimes primary) means of interacting with documents/text +or of sharing knowledge] + +What object numbers mean (unlike page numbers) is e.g. + + * if you cite text in any format, the resulting output can be reliably located + in any other document format type. Cite HTML and the reader can choose to + view in Epub or Pdf (the PDFs being an independent output, generated by + book publishing software XeTeX/LaTeX). + + * if you do a search, you can be given a result "index" indicating that your + search criteria is met by these documents, and at these specific locations + within each document, and the "index" is relevant not only for content + within the database, but for all document formats. + + * if you have a translated text prepared for sisu, then your citations are + relevant across languages e.g. you can specify exactly where in a Chinese + document text is to be found. + + * generated document index references & concordance list references etc. are + relevant across all output formats. + +What of search? For search, see the implications of object numbers for search +mentioned above. The system currently loads an SQL server (Postgresql) with +object sized text chunks. It could just as well populate an analytical engine +with larger sections or chapters of text for analytical purposes (such as the +currently popular Elasticsearch), whilst availing itself also of the concept of +objects and object numbers in search results. + +How do you deal with multilingual texts? If you have translated text prepared +for sisu, then your citations are relevant across languages. Object numbers +also provide an easy way to compare, discuss text (translations) across +languages. Text found/cited in one language has the same object number in its +translations, a given paragraph will be the same in another language, just +change the language code. (documents are prepared in UTF-8, current language +restrictions are: through use of LaTeX tools, Polyglosia & CJK (Chinese, +Japanese & Korean), and from the fact that sisu parses left to right) + +How are materials prepared for contribution to the collection? (a) The easiest +solution if the system allows is for submission in the format in which work is +authored, usually a word processor, for which odf may be a decent selection. +(b) I have stuck with enhanced plaintext, UTF-8 with minimal markup. Source +documents are prepared in UTF-8 text, with a minimalist native markup to +indicate the document structure (headings and their relative levels), +footnotes, and other document "features". This markup is easily parsable to the +human eye, and plays well with version control systems. Documents are prepared +in a text editor. Front ends such as markup assistants in a word processor that +can save to sisu text format or other tool whist possible do not exist. [(c) +yet another form of submission for collaborative work are wikis which have +shown their strength in efforts such as Wikipedia.] + +The system has proven to be a good testing ground for ideas and is flexible and +extensible. (things that could usefully be done: apart from a front end for +simpler user interaction; feed text to an analytical search engine, like +Elasticsearch/Lucene; it still needs a bibliography parser (auto-generation of +a bibliography from footnotes); and it might be useful to allow rough auto +translation documents on the fly by passing text through a translator (such as +Google translate)). + +In any event, my resulting technical opinions (in my modest domain of +action) may be regarded as encapsulated within SiSU +[http://www.sisudoc.org/] + +http://www.sisudoc.org/ +http://www.jus.uio.no/sisu/ + +git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary +(there may be additional commits in the upstream branch) +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream + +git clone git://git.sisudoc.org/git/doc/sisu-markup-samples.git --branch upstream +git clone --depth 1 git://git.sisudoc.org/git/doc/sisu-markup-samples.git --branch upstream +Development work is on Linux and the easiest way to install it is through the +Debian Linux package as this takes care of optional external dependencies such +as XeTeX for PDF output and Postgresql or Sqlite for search. + +** multiple document formats + +Text can be represented in multiple output formats with different +characteristics that are (or may be) regarded as strengths/advantages and +therefore preferred in different contexts. + +Given the different strengths and characteristics of various output formats, it +makes little sense to try too hard to make different representations of a +document look the same. More interesting is have document representations that +take advantage of each given outputs strengths. As valuable if not more so is +the ability to cite, find, discuss text with ease, across the different output +formats. + +For citation across output formats, SiSU uses object citation numbers. + +** document structure and document objects + +SiSU breaks marked up text into document structure and objects + +Document structure being the document heading hierarchy (having separated out +the document header). + +*** What are document objects? +An object is an identified meaningful unit of a document, most commonly a +paragraph of text, but also for example a table, code block, verse or image. + +SiSU tracks these substantive document units as document objects (and their +relationship to the document structure). + +** object citation numbers + +*** What are object citation numbers? + +An object citation number is a sequential number assigned to a document object. + +In sisu output documents share this common object numbering system (dubbed +"object citation numbering" (ocn)) that is meaningful (machine & human readable) +across various digital outputs whether paper, screen, or database oriented, +(PDF, html, XML, EPUB, sqlite, postgresql), and across multilingual content if +prepared appropriately. This numbering system can be used to reference content +across output types. + +*** Why might I want object citation numbering? + +The ability to cite and quickly locate text can be invaluable if not essential. + (whether for instruction or discussion). + +In this digital & Internet age we have multiple ways to represent documents and +multiple document output formats as options with different characteristics, +strengths/advantages etc. We need a way to cite text that works and is relevant +independent of the document format used. + +I want to discuss (cite) html text how do I do this? +how do I refer to / cite / discuss text in html? +Issue: html may be viewed online or printed, it is not tied to paper (as +e.g. pdf) and prints differently depending on selected font face and font size. + +I want to discuss (cite) text that is available in multiple formats (e.g. pdf, +epub, html) without having to worry about the output format that is referred +to. +How do I refer to / discuss text that is available in more than one format, +uncertain of what format is preferred, used or available to my colleagues? +e.g. html and epub or pdf have rather different text representations, how do I +discuss ... + +I would like to have a book index that is relevant (can be used) across multiple +output formats (e.g. pdf, epub, html) + +How do I make a book index (or a concordance file) that works across multiple +output formats? + +I would like to have search results indicating where in a document matches are +found and I would like it to be relevant across available output formats (e.g. +pdf, epub, html) +How do I get search results for locations of text within each relevant document + +I would like to be able to discuss a text that has been translated ... +how do I find text across languages? +Where I have a nicely translated document, how do I point to or discuss with my +foreign language counterpart some detail of the text, or, how do I point my +foreign language counterpart to the text I would like to bring to his +attention. + +** "Granular" Search + +Of interest is the ease of streaming documents to a relational database, at an +object (roughly paragraph) level and the potential for increased precision in +the presentation of matches that results thereby. The ability to serialize +html, LaTeX, XML, SQL, (whatever) is also inherent in / incidental to the +design. + +** Summary +SiSU information Structuring Universe +Structured information, Serialized Units <www.sisudoc.org> or +<www.jus.uio.no/sisu/> software for electronic texts, document collections, +books, digital libraries, and search, with "atomic search" and text positioning +system (shared text citation numbering: "ocn") +outputs include: plaintext, html, XHTML, XML, ODF (OpenDocument), EPUB, LaTeX, +PDF, SQL (PostgreSQL and SQLite) + +** SiSU Short Description + +SiSU is a comprehensive future-resilient electronic document management system. +Built-in search capabilities allow you to search across multiple documents and +highlight matches in an easy-to-follow format. Paragraph numbering system +allows you to cite your electronic documents in a consistent manner across +multiple file formats. Multiple format outputs allow you to display your +documents in plain text, PDF (portrait and horizontal), OpenDocument format, +HTML, or e-book reading format (EPUB). Word mapping allows you to easily create +word indexes for your documents. Future-resilient flexibility allows you to +quickly adapt your documents to newer output formats as needed. All these and +many other features are achieved with little or no additional work on your +documents - by marking up the documents with a super simplistic markup +language, leaving the SiSU engine to handle the heavy-lifting processing. + +Potential users of SiSU include individual authors who want to publish their +books or articles electronically to reach a broad audience, web publishers who +want to provide multiple channels of access to their electronic documents, or +any organizations which centrally manage a medium or large set of electronic +documents, especially governmental organizations which may prefer to keep their +documents in easily accessible yet non-proprietary formats. + +SiSU is an Open Source project initiated and led by Ralph Amissah +<ralph.amissah@gmail.com> and can be contacted via mailing list +<http://lists.sisudoc.org/listinfo/sisu> at <sisu@lists.sisudoc.org>. SiSU is +licensed under the GNU General Public License. + +*** notes + +For less markup than the most elementary HTML you can have more. SiSU - +Structured information, Serialized Units for electronic documents, is an +information structuring, transforming, publishing and search framework with the +following features: + +(i) markup syntax: (a) simpler than html, (b) mnemonic, influenced by +mail/messaging/wiki markup practices, (c) human readable, and easily writable, + +(ii) (a) minimal markup requirement, (b) single file marked up for multiple outputs, + + * documents are prepared in a single UTF-8 file using a minimalistic mnemonic +syntax. Typical literature, documents like "War and Peace" require almost no +markup, and most of the headers are optional. + + * markup is easily readable/parsed by the human eye, (basic markup is simpler +and more sparse than the most basic html), [this may also be converted to XML +representations of the same input/source document]. + + * markup defines document structure (this may be done once in a header +pattern-match description, or for heading levels individually); basic text +attributes (bold, italics, underscore, strike-through etc.) as required; and +semantic information related to the document (header information, extended +beyond the Dublin core and easily further extended as required); the headers +may also contain processing instructions. + +(iii) (a) multiple output formats, including amongst others: plaintext (UTF-8); +html; (structured) XML; ODF (Open Document text); EPUB; LaTeX; PDF (via LaTeX); +SQL type databases (currently PostgreSQL and SQLite). SiSU produces: +concordance files; document content certificates (md5 or sha256 digests of +headings, paragraphs, images etc.) and html manifests (and sitemaps of +content). (b) takes advantage of the strengths implicit in these very different +output types, (e.g. PDFs produced using typesetting of LaTeX, databases +populated with documents at an individual object/paragraph level, making +possible granular search (and related possibilities)) + +(iv) outputs share a common numbering system (dubbed "object citation +numbering" (ocn)) that is meaningful (to man and machine) across various +digital outputs whether paper, screen, or database oriented, (PDF, html, XML, +EPUB, sqlite, postgresql), this numbering system can be used to reference +content. + +(v) SQL databases are populated at an object level (roughly headings, +paragraphs, verse, tables) and become searchable with that degree of +granularity, the output information provides the object/paragraph numbers which +are relevant across all generated outputs; it is also possible to look at just +the matching paragraphs of the documents in the database; [output indexing also +work well with search indexing tools like hyperesteier]. + +(vi) use of semantic meta-tags in headers permit the addition of semantic +information on documents, (the available fields are easily extended) + +(vii) creates organised directory/file structure for (file-system) output, +easily mapped with its clearly defined structure, with all text objects +numbered, you know in advance where in each document output type, a bit of text +will be found (e.g. from an SQL search, you know where to go to find the +prepared html output or PDF etc.)... there is more; easy directory management +and document associations, the document preparation (sub-)directory may be used +to determine output (sub-)directory, the skin used, and the SQL database used, + +(viii) "Concordance file" wordmap, consisting of all the words in a document +and their (text/ object) locations within the text, (and the possibility of +adding vocabularies), + +(ix) document content certification and comparison considerations: (a) the +document and each object within it stamped with an sha256 hash making it +possible to easily check or guarantee that the substantive content of a document +is unchanged, (b) version control, documents integrated with time based source +control system, default RCS or CVS with use of $Id$ tag, which SiSU checks + +(x) SiSU's minimalist markup makes for meaningful "diffing" of the substantive +content of markup-files, + +(xi) easily skinnable, document appearance on a project/site wide, directory +wide, or document instance level easily controlled/changed, + +(xii) in many cases a regular expression may be used (once in the document +header) to define all or part of a documents structure obviating or reducing +the need to provide structural markup within the document, + +(xiii) prepared files may be batch process, documents produced are static files +so this needs to be done only once but may be repeated for various reasons as +desired (updated content, addition of new output formats, updated technology +document presentations/representations) + +(xiv) possible to pre-process, which permits: the easy creation of standard +form documents, and templates/term-sheets, or; building of composite documents +(master documents) from other sisu marked up documents, or marked up parts, +i.e. import documents or parts of text into a main document should this be +desired + +there is a considerable degree of future-resilience, output representations are +"upgradeable", and new document formats may be added. + +(xv) there is a considerable degree of future-resilience, output representations +are "upgradeable", and new document formats may be added: (a) modular, (thanks +in no small part to Ruby) another output format required, write another +module.... (b) easy to update output formats (eg html, XHTML, LaTeX/PDF +produced can be updated in program and run against whole document set), (c) +easy to add, modify, or have alternative syntax rules for input, should you +need to, + +(xvi) scalability, dependent on your file-system (ext3, Reiserfs, XFS, +whatever) and on the relational database used (currently Postgresql and +SQLite), and your hardware, + +(xvii) only marked up files need be backed up, to secure the larger document +set produced, + +(xviii) document management, + +(xix) Syntax highlighting for SiSU markup is available for a number of text +editors. + +(xx) remote operations: (a) run SiSU on a remote server, (having prepared sisu +markup documents locally or on that server, i.e. this solution where sisu is +installed on the remote server, would work whatever type of machine you chose +to prepare your markup documents on), (b) generated document outputs may be +posted by sisu to remote sites (using rsync/scp) (c) document source (plaintext +utf-8) if shared on the net may be identified by its url and processed locally +to produce the different document outputs. + +(xxi) document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) and +images and sent as a zip file called a sisupod, if shared on the net these too +may be processed locally to produce the desired document outputs, these may be +downloaded, shared as email attachments, or processed by running sisu against +them, either using a url or the filename. + +(xxii) for basic document generation, the only software dependency is Ruby, and +a few standard Unix tools (this covers plaintext, html, XML, ODF, EPUB, LaTeX). +To use a database you of course need that, and to convert the LaTeX generated +to PDF, a LaTeX processor like tetex or texlive. + +as a developers tool it is flexible and extensible + +** description + +SiSU ("SiSU information Structuring Universe" or "Structured information, +Serialized Units"),1 is a Unix command line oriented framework for document +structuring, publishing and search. Featuring minimalistic markup, multiple +standard outputs, a common citation system, and granular search. Using markup +applied to a document, SiSU can produce plain text, HTML, XHTML, XML, +OpenDocument, LaTeX or PDF files, and populate an SQL database with objects2 +(equating generally to paragraph-sized chunks) so searches may be performed and +matches returned with that degree of granularity (e.g. your search criteria is +met by these documents and at these locations within each document). Document +output formats share a common object numbering system for locating content. +This is particularly suitable for "published" works (finalized texts as opposed +to works that are frequently changed or updated) for which it provides a fixed +means of reference of content. How it works + +SiSU markup is fairly minimalistic, it consists of: a (largely optional) +document header, made up of information about the document (such as when it was +published, who authored it, and granting what rights) and any processing +instructions; and markup within text which is related to document structure and +typeface. SiSU must be able to discern the structure of a document, (text +headings and their levels in relation to each other), either from information +provided in the instruction header or from markup within the text (or from a +combination of both). Processing is done against an abstraction of the document +comprising of information on the document's structure and its objects,2 which +the program serializes (providing the object numbers) and which are assigned +hash sum values based on their content. This abstraction of information about +document structure, objects, (and hash sums), provides considerable flexibility +in representing documents different ways and for different purposes (e.g. +search, document layout, publishing, content certification, concordance etc.), +and makes it possible to take advantage of some of the strengths of established +ways of representing documents, (or indeed to create new ones). + +1. also chosen for the meaning of the Finnish term "sisu". + +2 objects include: headings, paragraphs, verse, tables, images, but not +footnotes/endnotes which are numbered separately and tied to the object from +which they are referenced. + +More information on SiSU provided at: <www.sisudoc.org/sisu/SiSU> + +SiSU was developed in relation to legal documents, and is strong across a wide +variety of texts (law, literature...(humanities, law and part of the social +sciences)). SiSU handles images but is not suitable for formulae/ statistics, +or for technical writing at this time. + +SiSU has been developed and has been in use for several years. Requirements to +cover a wide range of documents within its use domain have been explored. + +<ralph@amissah.com> +<ralph.amissah@gmail.com> +<sisu@lists.sisudoc.org> +<http://lists.sisudoc.org/listinfo/sisu> +2010 +w3 since October 3 1993 +* Finding SiSU +** source +http://git.sisudoc.org/gitweb/ + +*** sisu +sisu git repo: +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary + +**** most recent source without repo history +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream +**** full clone +git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + +*** sisu-markup-samples git repo: +http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary + +** mailing list +sisu at lists.sisudoc.org +http://lists.sisudoc.org/listinfo/sisu + +** irc oftc #sisu + +** home pages + <http://www.sisudoc.org/> + <http://search.sisudoc.org/> + <http://www.jus.uio.no/sisu> + +* Installation + +** where you take responsibility for having the correct dependencies + +Provided you have *Ruby*, *SiSU* can be run. + +SiSU should be run from the directory containing your sisu marked up document +set. + +This works fine so long as you already have sisu external dependencies in +place. For many operations such as html, epub, odt this is likely to be fine. +Note however, that additional external package dependencies, such as texlive +(for pdfs), sqlite3 or postgresql (for search) should you desire to use them +are not taken care of for you. + +*** run off the source tarball without installation + +RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) +.......................................................... + +**** 1. Obtain the latest sisu source + +using git: + +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log + + git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream + +or, identify latest available source: + +https://packages.debian.org/sid/sisu +http://packages.qa.debian.org/s/sisu.html +http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org + +http://sisudoc.org/sisu/archive/pool/main/s/sisu/ + +and download the: + + sisu_5.4.5.orig.tar.xz + +using debian tool dget: + +The dget tool is included within the devscripts package +https://packages.debian.org/search?keywords=devscripts +to install dget install devscripts: + + apt-get install devscripts + +and then you can get it from Debian: + dget -xu http://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc + +or off sisu repos + dget -x http://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc +or + dget -x http://sisudoc.org/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc + +**** 2. Unpack the source + +Provided you have *Ruby*, *SiSU* can be run without installation straight from +the source package directory tree. + +Run ruby against the full path to bin/sisu (in the unzipped source package +directory tree). SiSU should be run from the directory containing your sisu +marked up document set. + + ruby ~/sisu-5.4.5/bin/sisu --html -v document_name.sst + +This works fine so long as you already have sisu external dependencies in +place. For many operations such as html, epub, odt this is likely to be fine. +Note however, that additional external package dependencies, such as texlive +(for pdfs), sqlite3 or postgresql (for search) should you desire to use them +are not taken care of for you. + +*** gem install (with rake) + +(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install +the gem + +Provided you have ruby & rake, this can be done with the single command: + + rake gem_create_build_install + +to build and install sisu v5 & sisu v6, alias gemcbi + +separate gems are made/installed for sisu v5 & sisu v6 contained in source. + +to build and install sisu v5, alias gem5cbi: + + rake gem_create_build_install_stable + +to build and install sisu v6, alias gem6cbi: + + rake gem_create_build_install_unstable + +for individual steps (create, build, install) see rake options, rake -T to +specify sisu version for sisu installed via gem + + gem search sisu + + sisu _5.4.5_ --version + + sisu _6.0.11_ --version + +to uninstall sisu installed via gem + + sudo gem uninstall --verbose sisu + +For a list of alternative actions you may type: + + rake help + + rake -T + +Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> + +*** installation with setup.rb + +this is a three step process, in the root directory of the unpacked *SiSU* as +root type: + +ruby setup.rb config +ruby setup.rb setup +#[as root:] +ruby setup.rb install + +further information: +<http://i.loveruby.net/en/projects/setup/> +<http://i.loveruby.net/en/projects/setup/doc/usage.html> + + ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install + +** Debian install + +*SiSU* is available off the *Debian* archives. It should necessary only to run +as root, Using apt-get: + + apt-get update + + apt get install sisu-complete + +(all sisu dependencies should be taken care of) + +If there are newer versions of *SiSU* upstream, they will be available by +adding the following to your sources list /etc/apt/sources.list + +#/etc/apt/sources.list + +deb http://www.jus.uio.no/sisu/archive unstable main non-free +deb-src http://www.jus.uio.no/sisu/archive unstable main non-free + +The non-free section is for sisu markup samples provided, which contain +authored works the substantive text of which cannot be changed, and which as a +result do not meet the debian free software guidelines. + +*SiSU* is developed on *Debian*, and packages are available for *Debian* that +take care of the dependencies encountered on installation. + +The package is divided into the following components: + + *sisu*, the base code, (the main package on which the others depend), without + any dependencies other than ruby (and for convenience the ruby webrick web + server), this generates a number of types of output on its own, other + packages provide additional functionality, and have their dependencies + + *sisu-complete*, a dummy package that installs the whole of greater sisu as + described below, apart from sisu -examples + + *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated + + *sisu-postgresql*, dependencies used by sisu to populate postgresql database + (further configuration is necessary) + + *sisu-sqlite*, dependencies used by sisu to populate sqlite database + + *sisu-markup-samples*, sisu markup samples and other miscellany (under + *Debian* Free Software Guidelines non-free) + + *SiSU* is available off Debian Unstable and Testing [link: + <http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>] + [^1] install it using apt-get, aptitude or alternative *Debian* install tools. + +** Arch Linux + +* sisu markup :sisu:markup: + +** sisu markup + +#% structure - headings, levels + * headings (A-D, 1-3) + * inline + 'A~ ' NOTE title level + 'B~ ' NOTE optional + 'C~ ' NOTE optional + 'D~ ' NOTE optional + '1~ ' NOTE chapter level + '2~ ' NOTE optional + '3~ ' NOTE optional + '4~ ' NOTE optional :consider: + * node + * parent + * children + +#% font face NOTE open & close marks, inline within paragraph + * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold + * bold '!{ ... }!' + * italics '/{ ... }/' + * underscore '_{ ... }_' + * superscript '^{ ... }^' + * subscript ',{ ... },' + * strike '-{ ... }-' + * add '+{ ... }+' + * monospace '#{ ... }#' +#% para NOTE paragraph controls are at the start of a paragraph + * a para is a block of text separated from others by an empty line + * indent + * default, all '_1 ' up to '_9 ' + * first line hang '_1_0 ' + * first line indent further '_0_1 ' + * bullet + [levels 1-6] + '_* ' + '_1* ' + '_2* ' + * numbered list + [levels 1-3] + '# ' + +#% blocks NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be + * code + * [type of markup if any] + * poem + * group + * alt + * tables +#% boxes + NOTE grouped text with code block type color & possibly default image, warning, tip, red, blue etc. decide [NB N/A not implemented] + +#% notes NOTE inline within paragraph at the location where the note reference is to occur + * footnotes '~{ ... }~' + * [bibliography] [NB N/A not implemented] + +#% links, linking + * links - external, web, url + * links - internal + +#% images [multimedia?] + * images + * [base64 inline] [N/A not implemented] + +#% object numbers + * ocn (object numbers) + automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided) + +#% contents + * toc (table of contents) + autogenerated from structure/headings information + * index (book index) + built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text + +#% breaks + * line break ' \\ ' inline + * page break, column break ' -\\- ' start of line, breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. + * page break, page new ' =\\= ' start of line, breaks the page, starts a new page. + * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs) + +#% book type index + +#% comment + * comment + +#% misc + * term & definition + +** syntax hilighting + +*** vim +data/sisu/conf/editor-syntax-etc/vim/ +data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim + +*** emacs +data/sisu/conf/editor-syntax-etc/emacs/ +data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el + +* todo +sisu_todo.org diff --git a/data/doc/sisu/org/sisu_packaging.org b/data/doc/sisu/org/sisu_packaging.org new file mode 100644 index 00000000..3ef53fe7 --- /dev/null +++ b/data/doc/sisu/org/sisu_packaging.org @@ -0,0 +1,269 @@ +#+OPTIONS: ^:nil _:nil +Developer Notes, Dependencies + +* description +** short summary: 80 chars +smart text parser for document structuring, multiple format publishing & search +** longer + SiSU is a lightweight markup based, command line oriented, document + structuring, publishing and search framework for document collections. + . + With minimal preparation of a plain-text (UTF-8) file, using sisu markup + syntax in a text editor of your choice, SiSU can generate various document + formats (most of which share a common object numbering system for locating + content), including plain text, HTML, XHTML, XML, EPUB, OpenDocument text + (ODF:ODT), LaTeX, PDF files, and populate an SQL database with objects + (roughly paragraph-sized chunks) so searches may be performed and matches + returned with that degree of granularity. Think being able to finely match + text in documents, using object numbers, across different output formats (and + across languages if you have translations of the same document). Search results + can be an index of documents and object numbers within them, your criteria is + met by these documents at these locations within each document (equally + relevant across different output formats and languages). To be clear (if + obvious) page numbers provide none of this functionality. Object numbering is + particularly suitable for "published" works (finalized texts as opposed to + works that are frequently changed or updated) for which it provides a fixed + means of reference of content. Document outputs can also share provided + semantic meta-data. + . + SiSU also provides concordance files, document content certificates and + manifests of generated output. SiSU provides the means to make book indexes + that make use of its object numbering. + . + A vim syntax highlighting file and an ftplugin with folds for sisu markup is + provided. Vim 7 includes syntax highlighting for SiSU. Some syntax hilighting + is also available for Emacs and a few other editors. + . + Dependencies for various features are taken care of in sisu related packages. + The package sisu-complete installs the whole of SiSU. + . + Additional document markup samples are provided in the package + sisu-markup-samples which is found in the non-free archive. The licenses for + the substantive content of the marked up documents provided is that provided + by the author or original publisher. + . + SiSU uses utf-8 & parses left to right. Currently supported languages: + am bg bn br ca cs cy da de el en eo es et eu fi fr ga gl he hi hr hy ia is it + ja ko la lo lt lv ml mr nl nn no oc pl pt pt_BR ro ru sa se sk sl sq sr sv ta + te th tk tr uk ur us vi zh (see XeTeX polyglossia & cjk) + . + SiSU works well under po4a translation management, for which an administrative + sample Rakefile is provided with sisu_manual under markup-samples. +* Generic Dependencies +** source +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream +*** full source +git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + +** an install method + +$ qi setup --bin --lib --share --dryrun +$ sudo ./qi setup --bin --lib --share + +$ qi setup --bin --lib --share --conf --data --dryrun +$ sudo ./qi setup --bin --lib --share --conf --data + +$ qi setup --all --dryrun +$ sudo ./qi setup --all dryrun + +** minimal + needed for +---------------------- +ruby all, provides outputs text, html +xz sisupod +zip unzip epub & odt + +*** images +imagemagick | graphicsmagick +ruby-rmagick ? + +** special requirements + +*** pdf + +texlive +texlive-cjk +texlive-fonts ? +texlive-latex ? + +.sty (texpdf_format.rb) + +alltt.sty +amssymb.sty +babel.sty +boites.sty +color.sty +endnotes.sty +fancyhdr.sty +fontspec.sty +footmisc.sty +graphicx.sty +inputenc.sty +listings.sty +longtable.sty +manyfoot.sty +multicol.sty +parskip.sty +polyglossia.sty +soul.sty +textcomp.sty +thumbpdf.sty +titlepic.sty +ucs.sty +ulem.sty +url.sty +xetex.sty +xltxtra.sty +xunicode.sty + +*** sql db +**** sqlite3 + +sqlite3 +ruby-sqlite3 + +ruby-fcgi (fast-cgi) +httpd + +**** postgresql + +postgresql +ruby-pg + +ruby-fcgi (fast-cgi) +httpd + +*** qr codes + +qrencode + +*** maintenance/installation +ruby-thor | rake + +ruby-thor +rake + +* Debian Dependencies + +** source +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch debian/sid + +** debian/control (extract) + +Package: sisu +Depends: ${misc:Depends}, ruby | ruby-interpreter, rsync, unzip, zip, xz-utils +Recommends: + sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick | graphicsmagick, keychain, + openssh-client | lsh-client, openssl, po4a, qrencode, rake, ruby-rmagick, + ruby-thor, tidy, tree, vim-addon-manager +Suggests: sisu-markup-samples, lv, calibre, pinfo, poedit, texinfo, trang + +Package: sisu-complete +Depends: + ${misc:Depends}, sisu (= ${source:Version}), sisu-pdf (= ${source:Version}), + sisu-postgresql (= ${source:Version}), sisu-sqlite (= ${source:Version}), + imagemagick | graphicsmagick, openssl, qrencode, ruby-thor, tree +Suggests: sisu-markup-samples + +Package: sisu-pdf +Depends: + ${misc:Depends}, sisu (= ${source:Version}), + texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended, + texlive-latex-recommended, texlive-latex-extra, texlive-math-extra, + texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk +Suggests: evince | pdf-viewer + +Package: sisu-postgresql +Depends: + ${misc:Depends}, sisu (= ${source:Version}), + postgresql, ruby-pg, ruby-fcgi | libfcgi-ruby +Suggests: fcgiwrap, httpd, postgresql-contrib + +Package: sisu-sqlite +Depends: + ${misc:Depends}, sisu (= ${source:Version}), + sqlite3, ruby-sqlite3, ruby-fcgi | libfcgi-ruby +Suggests: fcgiwrap, httpd + +* Arch Linux Dependencies + +** source + +sisu-git + +full clone is more than is needed, so is limiting the branch + +git clone --branch upstream git://git.sisudoc.org/git/code/sisu.git + +try get a shallow clone that contains the last tag for git describe source version info + +git clone --depth 1 --branch upstream git://git.sisudoc.org/git/code/sisu.git +git clone --depth 1 --branch archlinux git://git.sisudoc.org/git/code/sisu.git + +git clone --depth 1 --no-single-branch --branch upstream \ + git://git.sisudoc.org/git/code/sisu.git + +*** git describe, source version +git describe --long --tags | sed 's/^sisu_//;s/\([^-]*-g\)/r\1/;s/-/./g' +git describe --long --tags | sed 's/^[a-z_-]\+//;s/\([^-]*-g\)/r\1/;s/-/./g' +git describe --long --tags | \ + sed 's/^[a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g' + +needs more than a shallow clone of depth 1 + +** pacman install + +sudo pacman -S ruby \ + zip unzip xy + +sudo pacman -S ruby \ + texlive-core texlive-latexextra texlive-fontsextra texlive-langcjk + +sudo pacman -S ruby \ + sqlite postgresql + +# issue with ruby-pg ruby-sqlite ruby-fcgi + +** interpreter + ruby + +** compression tools (epub, odf:odt, sisupod) + zip unzip + xy + +** texlive (pdf) +sudo pacman -S texlive-core texlive-latexextra +sudo pacman -S texlive-core texlive-latexextra texlive-fontsextra texlive-langcjk + +texlive-core extra/texlive-core +texlive-fontsextra extra/texlive-fontsextra +texlive-langcjk extra/texlive-langcjk + +*** .sty (called from texpdf_format.rb) +alltt.sty extra/texlive-core +amssymb.sty extra/texlive-core +babel.sty extra/texlive-core +boites.sty extra/texlive-latexextra +color.sty extra/texlive-core +endnotes.sty extra/texlive-latexextra +fancyhdr.sty extra/texlive-core +fontspec.sty extra/texlive-core +footmisc.sty extra/texlive-latexextra +graphicx.sty extra/texlive-core +inputenc.sty extra/texlive-core +listings.sty extra/texlive-core +longtable.sty extra/texlive-core +manyfoot.sty extra/texlive-latexextra +multicol.sty extra/texlive-core +parskip.sty extra/texlive-core +polyglossia.sty extra/texlive-core +soul.sty extra/texlive-latexextra +textcomp.sty extra/texlive-core +thumbpdf.sty extra/texlive-core +titlepic.sty extra/texlive-latexextra +ucs.sty extra/texlive-latexextra +ulem.sty extra/texlive-core +url.sty extra/texlive-core +xetex.sty ?? +xltxtra.sty extra/texlive-core +xunicode.sty extra/texlive-core |