From 569827db7fa44b1bd6b4069d458e2627bc6d658c Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 18 May 2014 08:35:15 -0400 Subject: documentation updates * sisu.org info on ruby-dbi removal affecting sisu in debian * sisu.org moved to data/doc/sisu (softlinked from root dir) * CHANGELOG simplify maintenance * note version changes * misc --- sisu.org | 2115 +------------------------------------------------------------- 1 file changed, 1 insertion(+), 2114 deletions(-) mode change 100644 => 120000 sisu.org (limited to 'sisu.org') diff --git a/sisu.org b/sisu.org deleted file mode 100644 index 0ddb2d2d..00000000 --- a/sisu.org +++ /dev/null @@ -1,2114 +0,0 @@ -#+PRIORITIES: A F E -(emacs:evil mode gifts a "vim" of "alternative" powers! ;) - -* 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] 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 - -*** 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 - -*** 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) - * -# is relevant only for 1~ dummy headings & instructs that they should be - removed from output where possible - * where -# is used on any other objects, it is treated the same way as ~# - -**** TODO [#B] collapsed level work out logic where dummy lev1 heading - - * exclude heading where lev1 '-#' - * means subsequent headings & text belong to parent heading (of lev1 -#) 1 level up - * ponder - - -**** TODO [#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) - -***** NOTES/COMMENTS - -debian/control, remove dependency on ruby-dbi, contained in sisu-postgresql and sisu-sqlite - -Result, status of next sisu release - * sisu-sqlite works fine, depends on ruby-sqlite3 - * sisu-postgresql is broken till fixed to work with ruby-pg (or ruby-dbi fixed) - * sample cgi search froms (cgi database query forms) are broken till - -**** TODO [#B] sisu-postgresql, fix - - * fix to work with ruby-pg (or if issue resolved reinstate ruby-dbi) - -**** TODO [#B] sisu sample cgi database query forms, fix - - * fix for sqlite3 & pg (as they currently depend on ruby-dbi) - -*** 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 -From: Daniel Baumann -Subject: manpages incomplete -Package: sisu -Version: 5.3.4-1 -Tag: upstream -Severity: normal - -sisu supports options like --verbose or --no-manifest, but they are not -listed in the sisu manpage. - -***** NOTES/COMMENTS - -documentation for sisu does lag a bit and has omissions, but I think you will -find that --verbose is documented, and --no-* options are listed under --exc-* -to which there is a pointer --no-manifest works but is actually ---no-links-to-manifest and is listed under aliases --exc-links-to-manifest and ---exc-manifest-links - -Will leave bug open as a reminder that updating is necessary and as there are -no doubt numerous issues for which this could be (re)opened - -**** TODO #746742 [n|u] please implement --no-metadata similar to --no-manifest - -Date: Sun, 13 Apr 2014 16:12:13 +0200 -From: Daniel Baumann -Subject: --no-manifest not working anymore -Package: sisu -Version: 5.3.4-1 -Severity: wishlist - -when running sisu-pdf with --no-manifest, the output (pdf) still -contains the sisu manifest at the end of the document. - -Regards, -Daniel - -*** DBT Outstanding bugs -- Wishlist items; Unclassified (24 bugs) :debian:dbt:wishlist: - -**** TODO [#D] #744352 [w|u] sisu output: aligning margin numbers when using 'code' - - -From: Daniel Baumann -To: 744352@bugs.debian.org -Subject: Re: sisu output: too many margin numbers -Date: Sun, 13 Apr 2014 17:27:10 +0200 -retitle 744352 sisu output: aligning margin numbers when using 'code' -severity 744352 wishlist -thanks - -sorry, i've looked wrongly at the output, the problem is simply an -aligning issue. it looks like that: - - foo bar. [1] - [2] - baz - - foo bar baz. [3] - -rather than: - - foo bar. [1] - - baz [2] - - foo bar baz. [3] - -Regards, -Daniel - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: too many margin numbers -Date: Sun, 13 Apr 2014 12:28:14 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist - -when using the following code: - -foo bar. - -code{ - - baz - -}code - -foo bar baz. - -the result in the output (pdf) is: - -foo bar. [1] - [2] -baz [3] - [4] -foo bar baz. [5] - -the '[n]' designates the margin number at the right site of the page. - -the problem is that sisu gives margin numbers to *empty* lines, which is -wrong. margin numbers should only be assigned to actual content. - -Regards, -Daniel - -***** NOTES/COMMENTS - -issue with pdf, look again, consider, -this is cosmetic, a fix should be found, but is not striaghtforward -alignment issue for code blocks not so easy to fix in some outputs, have so far ignored -this is an issue with other types of text block as well - -reason why this has not been addressed especially with code blocks: -the easiest fix would be to place the numbering at the end of the first line of a code block -however, as it is now, if you copy & paste a block of code you should get the code -if numbering is moved down to the first line, a copy of the code block will inlcude the -extraneous (to the code) object number -which is to my mind a bigger problem - -That said re pdf, LaTeX XeTeX are flexible, it may be possible to drop the ocn -at the start of a code block lower on its line so that it is closer to the code -that follows - -**** DONE (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 -To: Debian Bug Tracking System -Subject: please do not add '<' and '>' around links -Date: Sun, 13 Apr 2014 12:28:37 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist - -when using urls in sisu like this: - - http://example.org - -sisu then creates in the output (pdf) links like this: - - - -Please do not automagically add a '<' and '>' around urls. If the user -wants them, he would add one. - -Regards, -Daniel - -***** NOTES/COMMENTS - -is sisu default behavior, -would need to make configurable -url_visual_delimiters: '<>' -look into later - -**** 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 (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) - -**** TODO [#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 (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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu: empty sections are ignored -Date: Sun, 13 Apr 2014 17:09:32 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist - -if you have the following sisu syntax: - - :B~ foo - - 1~ foo1 - - foo1. - - 1~ foo2 - - foo2. - - :B~ bar - - 1~ bar1 - - 1~ bar2 - - :B~ baz - - 1~ baz1 - - 1~ baz2 - -then anything (including and) after ':B~ bar' is ignored entirely. - -***** NOTES/COMMENTS - -further info, have not yet been able to duplicate, -seemed to work (checked pdf & html (scroll & seg)) -was not able to reproduce -will look again - -**** DONE (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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu output: half-page title page in landscape output -Date: Sun, 13 Apr 2014 17:38:03 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist -Tags: upstream - -in a4 landscape output, there's always two pages on one page, which is -nice; except for the title page which spans over the whole page. - -it would be nice if the first page would be consistent to the same -scheme like the rest of the document - spanning only over the half of -the page. - -Regards, -Daniel - -***** NOTES/COMMENTS - -think about, should be fairly easily done, but am reluctant - -note the page numbering in landscape, the two landscape columns are given a single page number -it is really a landscape two column per-page text, provided primarily for screen viewing or -other convenience if found - -(many viewers provide two page per screen presentations, which would result in an effect similar to the one requested -the issue I guess might arise in that they are not printable on a single page? ... -but then the current settings are arguably justified) - -**** TODO [#C] #744396 [w|u] sisu output: "european" toc indenting - - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu output: "european" toc indenting -Date: Sun, 13 Apr 2014 17:40:53 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist -Tags: upstream - -by default, latex uses the following indenting in the TOC: - - 1. foo - 1.1 bar1 - 1.1.1 baz - 1.2 bar2 - -there's a latex option that i don't remember off-hand to have the -indenting like it's common in europe: - - 1. foo - 1.1 bar1 - 1.1.1 baz - 1.2 bar2 - -it would be nice if sisu could let the used decide which indenting style -to use for TOCs. - -Regards, -Daniel - -***** NOTES/COMMENTS - -will look at: should be possible; requires a configuration option - -**** DONE (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 (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 (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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu: possibility to influence content/formating of the title page -Date: Sun, 13 Apr 2014 18:32:14 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist -Tags: upstream - -by default, the title page (in the pdf output) shows @title and @creator. - -it would be nice if there would be a possibility to influence the -formatting (e.g. to have the title written in bold), and to have -additional possibilities to influence the content on the title page -(like the date or version, an url, or other text strings). - -Regards, -Daniel - -***** NOTES/COMMENTS - -consider, work on possibly, later - -**** TODO [#C] #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 .sst or .ssi -.sst files can be processed independently, -.ssi files are only insertions & cannot - -allowing .ssi to also include other .ssi or .sst could lead to recursive .ssi -allowing .ssm to also include other .ssm .ssi or .sst could lead to recursive .ssm - -stopping after an additional level of includes seems arbitrary, and possibly prone to error if you are dealing with many documents - -a possibility would be to have another file extension to flag the role of the file, -.ssmi (not very attractive) might do it -(providing visual cue signalling its role as both a master file and an insertion/included file that cannot be processed independently) -a .ssmi file must be included in a .ssm file -a .ssmi file (like .ssm) permits the inclusion only of .sst or .ssi files - -will work on eventually - -**** TODO [#C] #744409 [w|u] sisu output: urls in code blocks are not linkified - - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu output: urls in code blocks are not linkified -Date: Sun, 13 Apr 2014 18:41:09 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist -Tags: upstream - -it would be nice if urls written withiin code{...}code blocks would also -be automatically transformed into a link within the output (html). - -Regards, -Daniel - -***** NOTES/COMMENTS - -consider, so far code blocks are pretty much untouched ... not tampered with, -this could be done though - -**** 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 - - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu output: copy&past-able wrapped code blocks -Date: Sun, 13 Apr 2014 19:04:01 +0200 -Package: sisu -Version: 5.3.4-1 -Severity: wishlist -Tags: upstream - -if a line within a 'code{...}code' block is longer and needs to be -wrapped, sisu indicates the wrapping with an 'arrow' (←) symbol, which -is nice. - -it would be even nicer if the arrow would not 'selectable', so that when -you mark the line spanning over two lines with your mouse, the arrow is -not selected and thus not copy&pasted. - -i don't know how to do this, but it's possible within pdfs, as can be -seen in lots of pdfs in the internet. - -Regards, -Daniel - -***** NOTES/COMMENTS - -find out how and implement, further feedback on appropriate xetex tools welcome - -[Note: if can be applied to random characters, use may be of interest for -object numbers as well!] - -**** TODO [#C] #744734 [w|u] sisu output: replace all occurences of (C) rather than the first only - -From: Daniel Baumann -To: Debian Bug Tracking System -Subject: sisu output: replace all occurences of (C) rather than the first only -Date: Mon, 14 Apr 2014 06:11:13 +0200 - -Package: sisu -Version: 5.3.4-1 -Severity: wishlist -Tags: upstream - -if you have a '(C)' in :copyright:, it is automatically replaced with a -copyright symbol, which is nice, however, it sisu does that with the -first occurence only. - -so if you use: - - :copyright: (C) john doe
(C) jane doe - -then the second occurence is not replaced and that combination looks -very ugly. i suggest you replace all occurences of '(C)' to the -copyright symbol automatically. - -Regards, -Daniel diff --git a/sisu.org b/sisu.org new file mode 120000 index 00000000..cdc01b2b --- /dev/null +++ b/sisu.org @@ -0,0 +1 @@ +data/doc/sisu/sisu.org \ No newline at end of file -- cgit v1.2.3