sisu.org move stuff done to sisu-done.org
authorRalph Amissah <ralph@amissah.com>
Fri, 3 Oct 2014 23:13:06 +0000 (19:13 -0400)
committerRalph Amissah <ralph@amissah.com>
Fri, 3 Oct 2014 23:13:06 +0000 (19:13 -0400)
data/doc/sisu/sisu-done.org [new file with mode: 0644]
data/doc/sisu/sisu.org

diff --git a/data/doc/sisu/sisu-done.org b/data/doc/sisu/sisu-done.org
new file mode 100644 (file)
index 0000000..f39fcee
--- /dev/null
@@ -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
index d5e0ec5220faabf73a7d53069676ed2184300a0e..a5f8dbdc7f419c1f31af0f4f577e84e9e1d73586 100644 (file)
@@ -1137,74 +1137,12 @@ footnotes uses marker and endnote, check
 
 *** ruby 2.1
 
-**** DONE make sure sisu works
-
 *** TODO [#C] refactor ruby :ongoing:
 
 ** 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
-
 **** 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)
@@ -1220,156 +1158,6 @@ revisit,
 
 *** 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
-
 **** TODO ONGOING #746740 [n|u] manpages incomplete
 
 Date: Sat, 03 May 2014 08:45:49 +0200
@@ -1496,48 +1284,6 @@ 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
 
-**** 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
-
 **** TODO [#C] #744354 [w|u] sisu output: please do not add '<' and '>' around urls
 
 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
@@ -1569,360 +1315,6 @@ would need to make configurable
 url_visual_delimiters: '<>'
 look into later
 
-**** 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
 
 **** TODO [#B] #744390 [w|u] sisu: empty sections are ignored
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744390>
@@ -1968,66 +1360,6 @@ seemed to work (checked pdf & html (scroll & seg))
 was not able to reproduce
 will look again
 
-**** 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')
-
 **** TODO [#D] #744395 [w|u] sisu output: half-page title page in landscape output
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744395>
 
@@ -2099,101 +1431,6 @@ Daniel
 
 will look at: should be possible; requires a configuration option
 
-**** 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.
-
 **** 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>
 
@@ -2220,50 +1457,6 @@ Daniel
 
 consider, work on possibly, later
 
-**** 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
-
 **** TODO [#C] #744409 [w|u] sisu output: urls in code blocks are not linkified
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744409>
 
@@ -2287,38 +1480,6 @@ Daniel
 consider, so far code blocks are pretty much untouched ... not tampered with,
 this could be done though
 
-**** 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
-
 **** TODO [#C] #744685 [w|u] sisu output: copy&past-able wrapped code blocks
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744685>