documentation, notes, updatesisu_5.3.5

4 files changed, 152 insertions, 14 deletions

diff --git a/README b/README
index ef26c287..ffa05093 100644
--- a/README
+++ b/README
@@ -113,6 +113,7 @@ ruby setup.rb setup
 #[as root:]
 ruby setup.rb install
 
+
 further information:
 <http://i.loveruby.net/en/projects/setup/>
 <http://i.loveruby.net/en/projects/setup/doc/usage.html>
@@ -737,12 +738,12 @@ on its own, provides *SiSU* version information
 *-v [filename/wildcard]*
 see --verbose
 
-*--v3 [filename/wildcard]*
-invokes the sisu v3 document parser/generator. You may run sisu3 instead.
+*--v5 [filename/wildcard]*
+invokes the sisu v5 document parser/generator. You may run sisu5 instead. This
+is the current default and is normally omitted.
 
-*--v4 [filename/wildcard]*
-invokes the sisu v4 document parser/generator. This is the default and is
-normally omitted.
+*--v6 [filename/wildcard]*
+invokes the sisu v6 document parser/generator. You may run sisu6 instead.
 
 *--verbose [filename/wildcard]*
 provides verbose output of what is being generated, where output is placed (and
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
index 19ce3db5..356f38e1 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
@@ -390,11 +390,11 @@ on its own, provides SiSU version information
 !_ -v [filename/wildcard] \\
 see --verbose
 
-!_ --v3 [filename/wildcard] \\
-invokes the sisu v3 document parser/generator. You may run sisu3 instead.
+!_ --v5 [filename/wildcard] \\
+invokes the sisu v5 document parser/generator. You may run sisu5 instead. This is the current default and is normally omitted.
 
-!_ --v4 [filename/wildcard] \\
-invokes the sisu v4 document parser/generator. This is the default and is normally omitted.
+!_ --v6 [filename/wildcard] \\
+invokes the sisu v6 document parser/generator. You may run sisu6 instead.
 
 !_ --verbose [filename/wildcard] \\
 provides verbose output of what is being generated, where output is placed (and error messages if any), as with -u flag provides a url mapping of files created for each of the processing flag requests. Alias -v
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index eb43129c..3e85a9db 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -653,12 +653,12 @@ version information
 .B -v [filename/wildcard]
 see --verbose
 .TP
-.B --v3 [filename/wildcard]
-invokes the sisu v3 document parser/generator. You may run sisu3 instead.
+.B --v5 [filename/wildcard]
+invokes the sisu v5 document parser/generator. You may run sisu5 instead. This
+is the current default and is normally omitted.
 .TP
-.B --v4 [filename/wildcard]
-invokes the sisu v4 document parser/generator. This is the default and is
-normally omitted.
+.B --v6 [filename/wildcard]
+invokes the sisu v6 document parser/generator. You may run sisu6 instead.
 .TP
 .B --verbose [filename/wildcard]
 provides verbose output of what is being generated, where output is placed (and
diff --git a/sisu.org b/sisu.org
index ff348dea..0ddb2d2d 100644
--- a/sisu.org
+++ b/sisu.org
@@ -1008,6 +1008,30 @@ revisit,
   * 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:
     <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=sisu>
 
@@ -1093,6 +1117,17 @@ 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
@@ -1177,6 +1212,24 @@ 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:
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744353>
 
@@ -1243,6 +1296,13 @@ 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:
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744355>
 
@@ -1560,6 +1620,21 @@ having an empty line in between like this:
 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)
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744386>
 
@@ -1620,6 +1695,13 @@ if you have the following sisu syntax:
 
 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:
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744391>
 
@@ -1702,6 +1784,18 @@ the page.
 Regards,
 Daniel
 
+***** NOTES/COMMENTS
+
+think about, should be fairly easily done, but am reluctant
+
+note the page numbering in landscape, the two landscape columns are given a single page number
+it is really a landscape two column per-page text, provided primarily for screen viewing or
+other convenience if found
+
+(many viewers provide two page per screen presentations, which would result in an effect similar to the one requested
+the issue I guess might arise in that they are not printable on a single page? ...
+but then the current settings are arguably justified)
+
 **** TODO [#C] #744396 [w|u] sisu output: "european" toc indenting
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744396>
 
@@ -1735,6 +1829,10 @@ 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)
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744399>
 
@@ -1852,6 +1950,10 @@ additional possibilities to influence the content on the title page
 Regards,
 Daniel
 
+***** NOTES/COMMENTS
+
+consider, work on possibly, later
+
 **** TODO [#C] #744408 [w|u] sisu: support more than one level of includes/nested includes
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744408>
 
@@ -1873,6 +1975,29 @@ 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
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744409>
 
@@ -1891,6 +2016,11 @@ 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
       <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744541>
 
@@ -1949,6 +2079,13 @@ seen in lots of pdfs in the internet.
 Regards,
 Daniel
 
+***** NOTES/COMMENTS
+
+find out how and implement, further feedback on appropriate xetex tools welcome
+
+[Note: if can be applied to random characters, use may be of interest for
+object numbers as well!]
+
 **** TODO [#C] #744734 [w|u] sisu output: replace all occurences of (C) rather than the first only
 
 From: Daniel Baumann <daniel.baumann@progress-technologies.net>