From 3883915a5fddac4aa6114f80cb2ef6634a4bfe6b Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Fri, 3 Oct 2014 19:13:06 -0400 Subject: sisu.org move stuff done to sisu-done.org --- data/doc/sisu/sisu-done.org | 1987 +++++++++++++++++++++++++++++++++++++++++++ data/doc/sisu/sisu.org | 839 ------------------ 2 files changed, 1987 insertions(+), 839 deletions(-) create mode 100644 data/doc/sisu/sisu-done.org diff --git a/data/doc/sisu/sisu-done.org b/data/doc/sisu/sisu-done.org new file mode 100644 index 00000000..f39fcee1 --- /dev/null +++ b/data/doc/sisu/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 + * + * + * + +** 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: + +**** 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: + + + + 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: + ] + [^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 + + + + + + +xml editor vim emacs + +nXML plugin + + + + + +emacs.txt evil.txt + + + + +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 + + + + + + + + + + + + + + + + + + + +***** 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 + + [] 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) + +#% misc + +**** TODO [#D] fictionbook :feature: + +***** urls +#% fictionbook xml.txt + + + + + + + + + + +***** 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 + + + + + + + + + + + + +**** 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 + + + + +**** TODO [#E] Literature Markup Language - :feature: + +***** urls +%% Literature Markup Language - + +"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 - 1.1 + + +**** TODO [#E] TEI Lite (Text Encoding Initiative) :feature: + +***** urls +%% TEI Lite (Text Encoding Initiative) + + + +*** Text :txt: + +sisu_markup.txt asciidoc.txt markdown.txt textile.txt rst.txt + +**** TODO [#D] asciidoc :feature: + +***** urls +#% asciidoc + + + + + +cheatsheets + + + + + + + + + + +***** 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 + + + + + + + +Markdown supports two styles of headers, Setext and atx +Setext + + +atx + + + + + + + + + + + + + + +#% pandoc markdown + + + + + + + +#% multimarkdown + + +#% markdown pandoc v multimarkdown + + +#% rST v markdown + + +***** 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 + + + + + + + + +#% rST v markdown + + +***** 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: + or + External hyperlinks, like `Python + `_. + [] 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 + +v2.4 + +v2 + + +***** 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: + + +**** DONE (5.3.5::6.0.5) [#B] #744360 [n|u] sisu: includes do not work properly :processing:fix: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + + +where as '' 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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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.
Foo bar baz http://example.org. + +but it doesn't work if there's no space: + + Foo bar baz http://example.org.
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
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 + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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) + + +From: Daniel Baumann +To: Debian Bug Tracking System +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

, :B +equals

, and :C equals

. currently, (in that analogy), :B and :C +both equal

. + +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 + + +From: Daniel Baumann +To: Debian Bug Tracking System +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) + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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 +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) + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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: + + +From: Daniel Baumann +To: Debian Bug Tracking System +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 + + +From: Daniel Baumann +To: Debian Bug Tracking System +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 + + +From: Daniel Baumann +To: Debian Bug Tracking System +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/sisu.org b/data/doc/sisu/sisu.org index d5e0ec52..a5f8dbdc 100644 --- a/data/doc/sisu/sisu.org +++ b/data/doc/sisu/sisu.org @@ -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: - - -**** DONE (5.3.5::6.0.5) [#B] #744360 [n|u] sisu: includes do not work properly :processing:fix: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - - -where as '' 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 @@ -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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.
Foo bar baz http://example.org. - -but it doesn't work if there's no space: - - Foo bar baz http://example.org.
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
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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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) - - -From: Daniel Baumann -To: Debian Bug Tracking System -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

, :B -equals

, and :C equals

. currently, (in that analogy), :B and :C -both equal

. - -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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -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) - - -From: Daniel Baumann -To: Debian Bug Tracking System -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 @@ -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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 -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 @@ -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) - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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: - - -From: Daniel Baumann -To: Debian Bug Tracking System -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 @@ -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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -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 @@ -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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -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 -- cgit v1.2.3