From e2f6efc6f18a86b8a5e2da1bcd9ffc6f84a6d389 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Mon, 12 May 2014 23:18:54 -0400 Subject: documentation, notes, update --- README | 11 +- .../markup-samples/manual/en/sisu_commands.sst | 8 +- man/man1/sisu.1 | 10 +- sisu.org | 137 +++++++++++++++++++++ 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: @@ -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: @@ -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: @@ -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: @@ -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) @@ -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: @@ -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 @@ -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) @@ -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 @@ -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 @@ -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 @@ -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 -- cgit v1.2.3