Merge tag 'sisu_5.3.5' into debian/sid
[software/sisu] / sisu.org
1 #+PRIORITIES: A F E
2 (emacs:evil mode gifts a "vim" of "alternative" powers! ;)
3
4 * Markup :sisu:markup:
5
6 ** sisu
7
8 #% structure - headings, levels
9 * headings (A-D, 1-3)
10 * inline
11 'A~ ' NOTE title level
12 'B~ ' NOTE optional
13 'C~ ' NOTE optional
14 'D~ ' NOTE optional
15 '1~ ' NOTE chapter level
16 '2~ ' NOTE optional
17 '3~ ' NOTE optional
18 '4~ ' NOTE optional :consider:
19 * node
20 * parent
21 * children
22
23 #% font face NOTE open & close marks, inline within paragraph
24 * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold
25 * bold '!{ ... }!'
26 * italics '/{ ... }/'
27 * underscore '_{ ... }_'
28 * superscript '^{ ... }^'
29 * subscript ',{ ... },'
30 * strike '-{ ... }-'
31 * add '+{ ... }+'
32 * monospace '#{ ... }#'
33 #% para NOTE paragraph controls are at the start of a paragraph
34 * a para is a block of text separated from others by an empty line
35 * indent
36 * default, all '_1 ' up to '_9 '
37 * first line hang '_1_0 '
38 * first line indent further '_0_1 '
39 * bullet
40 [levels 1-6]
41 '_* '
42 '_1* '
43 '_2* '
44 * numbered list
45 [levels 1-3]
46 '# '
47
48 #% blocks NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be
49 * code
50 * [type of markup if any]
51 * poem
52 * group
53 * alt
54 * tables
55 #% boxes
56 NOTE grouped text with code block type color & possibly default image, warning, tip, red, blue etc. decide [NB N/A not implemented]
57
58 #% notes NOTE inline within paragraph at the location where the note reference is to occur
59 * footnotes '~{ ... }~'
60 * [bibliography] [NB N/A not implemented]
61
62 #% links, linking
63 * links - external, web, url
64 * links - internal
65
66 #% images [multimedia?]
67 * images
68 * [base64 inline] [N/A not implemented]
69
70 #% object numbers
71 * ocn (object numbers)
72 automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided)
73
74 #% contents
75 * toc (table of contents)
76 autogenerated from structure/headings information
77 * index (book index)
78 built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text
79
80 #% breaks
81 * line break ' \\ ' inline
82 * 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.
83 * page break, page new ' =\\= ' start of line, breaks the page, starts a new page.
84 * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs)
85
86 #% book type index
87
88 #% comment
89 * comment
90
91 #% misc
92 * term & definition
93
94 ** proposals/additions
95
96 *** TODO [#B] markup syntax code block, indicate syntax of code :feature:
97 ``` code:ruby
98
99 *** TODO [#C] colored boxes round text :feature:ponder:
100 ``` box:red (select color of box)
101 ``` box:warn ``` box:tip (some default boxes? decide)
102 ``` box:red:"Warn" (select color and lead text of box, else instead
103 select color box & use regular single line bold markup ^!_ Warn$)
104
105 *** TODO [#D] bibliography :feature:ponder:
106
107 *** TODO speaker, as e.g. play (irc?) :feature:ponder:
108 ``` Ophelia:
109 ::Ophelia
110
111 *** TODO [#F] time stamp (e.g. for irc, video text?):feature:ponder:
112 ``` 04:03
113 ``` 04:03 ... 07:12
114 ``` 04:03 + 03:09
115 ``` 12:04:03
116 ``` 12:04:03 ... 12:07:12
117 ``` 12:04:03 + 03:09
118 probably not worth the effort, as time stamp is an alternative
119 identifying number (to ocn, and ∴ sisu objects not ideal)
120
121 *** TODO book index, alternative based on search within text
122
123 ** syntax hilighting
124
125 *** vim
126 data/sisu/conf/editor-syntax-etc/vim/
127 data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim
128
129 *** emacs
130 data/sisu/conf/editor-syntax-etc/emacs/
131 data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el
132
133 * Document Abstraction :sisu:doc_abstr:
134
135 ** TODO [#D] XML middle layer?
136
137 *** XMLda sisu
138 consder alternative sisu layer in XML
139
140 *** TODO [#D] RelaxNG sisu
141
142 * Output :sisu:output:
143
144 ** New outputs
145
146 *** XML :xml:
147 %% xml, docbook.txt fictionbook.txt xldl.txt lml.txt tei.txt emacs.txt
148 <http://xml.silmaril.ie/>
149 <http://www.xml.com/>
150 <http://programming.oreilly.com/2012/08/shrinking-and-stretching-the-boundaries-of-markup.htmlhttp://programming.oreilly.com/2012/08/shrinking-and-stretching-the-boundaries-of-markup.html>
151
152 <http://broadcast.oreilly.com/2012/03/xmls-dialect-problem.html>
153
154 xml editor vim emacs
155 <http://chimera.labs.oreilly.com/books/1234000000058/ch01.html#which_xml_editor_should_i_use>
156 nXML plugin
157 <http://blog.tommorris.org/post/2456183251/emacs-and-nxml-survival-guide>
158 <http://johnbokma.com/mexit/2008/10/01/nxml-emacs-how-to.html>
159 <http://www.emacswiki.org/cgi-bin/wiki/NxmlModeForXHTML>
160 <http://www.xmlhack.com/read.php_item=2061>
161 <http://infohost.nmt.edu/tcc/help/pubs/nxml/index.html>
162 emacs.txt evil.txt
163
164 <http://www.oreillynet.com/xml/blog/2005/10/smart_quotes_and_more_in_vim_a.html>
165 <http://stackoverflow.com/questions/1430164/differences-between-emacs-and-vim>
166
167 To validate a book.xml file using xmllint, run the following command:
168 $ xmllint --postvalid --xinclude --noout book.xml
169
170 The default location where xmllint will look for the catalog file is
171 /etc/xml/catalog. Alternatively, you can set the environment variable
172 XML_CATALOG_FILES to define another default location for catalog
173 files. Once you’ve got the DTD and catalog set up locally, you can
174 validate as before:
175 $ xmllint --postvalid --xinclude --noout book.xml
176
177 %% Docbook
178 docbook.txt
179
180 %% Fictionbook
181 fictionbook.txt
182
183 %% XLDL
184 xldl.txt
185
186 %% Literature Markup Language
187 lml.txt
188
189 %% Text Encoding Initiative
190 tei.txt
191
192 **** TODO [#B] docbook :feature:
193
194 ***** urls
195 #% docbook book xml.txt
196 <http://www.docbook.org>
197 <http://www.sagehill.net/docbookxsl/index.html>
198 <http://wiki.docbook.org/>
199 <http://www.docbook.org/tdg5/en/html/>
200 <http://www.docbook.org/tdg5/en/html/docbook.html>
201 <http://www.docbook.org/tdg5/en/html/ch01.html>
202 <http://www.docbook.org/tdg5/en/html/ch02.html>
203 <http://www.sagehill.net/docbookxsl/index.html>
204
205 <http://www.docbook.org/schemas/5x>
206 <http://www.docbook.org/xml/5.0/>
207
208 <http://infohost.nmt.edu/tcc/help/pubs/docbook5/web/index.html>
209
210 <http://docbook.org/xml/5.0/rng/docbook.rng>
211 <http://docbook.org/xml/5.0/rng/docbook.rnc>
212
213 <http://www.cuddletech.com/blog/pivot/entry.php?id=509>
214
215 ***** rb file
216 lib/sisu/v6/xml_docbook5.rb
217
218 ***** transformations :transform:markup_docbook:
219 #% structure - headings, levels
220 [] sisu (A-C, 1-3)
221 [] collapsed (1-6) (decoration)
222 [] node (child, parent ...)
223
224 #% font face
225 [] bold
226 [] italics
227 [] underscore
228 [] superscript
229 [] subscript
230 [] strike
231 [] add
232
233 #% para
234 [] default
235 [] indent
236 [] default, all
237 [] first line hang or indent further
238 [] bullet
239
240 #% blocks
241 <http://www.docbook.org/tdg5/en/html/literallayout.html>
242 [] code
243 [] [type of markup if any]
244 [] poem
245 [] group
246 [] alt
247 [] tables
248
249 #% notes
250 [] footnotes
251 [] [bibliography?]
252
253 #% links, linking
254 [] links - external, web, url
255 [] links - internal
256
257 #% images [multimedia?]
258 [] images
259 [] [base 64]
260
261 #% object numbers
262 [] ocn (object numbers)
263
264 #% contents
265 [] toc (table of contents)
266 <http://www.docbook.org/tdg5/en/html/toc.html>
267 [] index (book index)
268
269 #% misc
270
271 **** TODO [#D] fictionbook :feature:
272
273 ***** urls
274 #% fictionbook xml.txt
275 <http://en.wikipedia.org/wiki/FictionBook>
276 <http://fictionbook.org/index.php/Eng:FictionBook>
277 <http://fictionbook.org/index.php/Eng:Articles>
278 <http://fictionbook.org/index.php/Eng:Documentations>
279 <http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1>
280 <http://www.fictionbook.org/index.php/Eng:FictionBook>
281 <http://fictionbook-lib.org/>
282 <http://fictionbook-lib.org/browse.php>
283 <http://wiki.mobileread.com/wiki/FB2>
284
285 ***** rb file
286 lib/sisu/v6/xml_fictionbook2.rb
287
288 ***** transformations :transformations:markup_fictionbok: #%
289 #% structure - headings, levels
290 [] sisu (A-C, 1-3)
291 [] collapsed (1-6) (decoration)
292 [] node (child, parent ...)
293
294 #% font face
295 [] bold
296 [] italics
297 [] underscore
298 [] superscript
299 [] subscript
300 [] strike
301 [] add
302 [] monospace
303
304 #% para
305 [] default
306 [] indent
307 [] default, all
308 [] first line hang or indent further
309 [] bullet
310
311 #% blocks
312 [] code
313 [] [type of markup if any]
314 [] poem
315 [] group
316 [] alt
317 [] tables
318
319 #% notes
320 [] footnotes
321 [] [bibliography?]
322
323 #% links, linking
324 [] links - external, web, url
325 [] links - internal
326
327 #% images [multimedia?]
328 [] images
329 [] [base 64]
330
331 #% object numbers
332 [] ocn (object numbers)
333
334 #% contents
335 [] toc (table of contents)
336 [] index (book index)
337
338 #% breaks
339 [] line break
340 [] horizontal rule
341 [] column break
342 [] page break
343
344 #% comment
345 [] comment
346
347 #% misc
348
349 <http://en.wikipedia.org/wiki/FictionBook>
350 <http://fictionbook.org/index.php/Eng:FictionBook>
351 <http://fictionbook.org/index.php/Eng:Articles>
352 <http://fictionbook.org/index.php/Eng:Documentations>
353 <http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1>
354 <http://www.fictionbook.org/index.php/Eng:FictionBook>
355
356 <http://www.fictionbook.org/index.php/%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80_%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0_%D0%B2_FB2>
357
358 <https://addons.mozilla.org/en-US/firefox/addon/fb2-reader/>
359
360 **** TODO [#D] XLDL :feature:
361
362 ***** urls
363 %% xml.txt xldl - novels, stories, poems
364 Name: XLDL - an XML doctype for novels, stories, poems, playsName: XLDL - an XML doctype for novels, stories, poems, plays
365 <http://www.ister.org/code/xldl/>
366 <http://www.ister.org/code/xldl/doc/xldl.dtd.html>
367 <line> <stanza>
368
369 **** TODO [#E] Literature Markup Language - <LML /> :feature:
370
371 ***** urls
372 %% Literature Markup Language - <LML />
373 <http://hoffmann.bplaced.net/lml/>
374 "It is assumed, that there are three quite different techniques to provide text,
375 respectively three types of text, this is prose and poetry and code (for
376 example source code of computer programs or from markup languages)."
377 Suggestions and Ideas for Literature Markup Language - <LML /> 1.1
378 <http://hoffmann.bplaced.net/lml/lml1.1.php>
379
380 **** TODO [#E] TEI Lite (Text Encoding Initiative) :feature:
381
382 ***** urls
383 %% TEI Lite (Text Encoding Initiative)
384 <http://www.tei-c.org/Guidelines/Customization/Lite/>
385 <http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_lite.doc.html>
386
387 *** Text :txt:
388
389 sisu_markup.txt asciidoc.txt markdown.txt textile.txt rst.txt
390
391 **** TODO [#D] asciidoc :feature:
392
393 ***** urls
394 #% asciidoc
395 <http://asciidoc.org/>
396 <http://asciidoctor.org/>
397 <http://www.methods.co.nz/asciidoc/>
398 <http://en.wikipedia.org/wiki/AsciiDoc>
399
400 cheatsheets
401 <http://powerman.name/doc/asciidoc>
402 <http://powerman.name/doc/asciidoc-index>
403
404 <http://www.methods.co.nz/asciidoc/asciidoc.txt>
405 <http://www.methods.co.nz/asciidoc/userguide.html>
406
407 <http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html>
408 <http://www.methods.co.nz/asciidoc/asciidoc.html>
409 <http://www.methods.co.nz/asciidoc/chunked/index.html>
410
411 ***** rb file
412 lib/sisu/v6/txt_asaciidoc.rb
413
414 ***** transformations :transformations:markup_asciidoc: #%
415 #% structure - headings, levels
416 [] sisu (A-C, 1-3)
417 [] collapsed (1-4) (decoration)
418 [] inline
419 '== '
420 '=== '
421 '==== '
422 '===== '
423 ''
424 ''
425 [] underscore
426 '-'
427 '~'
428 '^'
429 '+'
430 '' ['.' proposed]
431 '' ['.' proposed]
432 [] node (child, parent ...)
433
434 #% font face
435 [open & close marks]
436 [] bold
437 '*'
438 [] italics
439 '_'
440 [] underscore
441 ''
442 [] superscript
443 '^'
444 [] subscript
445 '~'
446 [] strike
447 '-'
448 [] add
449 [] monospace
450 '+'
451 '`' pass markup through unchanged, monospace code
452
453 #% para
454 [] default
455 [] indent
456 [] default, all
457 [] first line hang or indent further
458 [] bullet
459 [levels 1-6]
460 '*'
461 '**'
462 '***'
463 '****'
464 '*****'
465 '*******'
466 [] numbered list
467 [levels 1-3]
468 '. ' number
469 '.. ' lower alpha
470 '... ' lower roman
471 '.... ' upper alpha
472 '..... ' upper roman
473
474 #% blocks
475 [] code
476 [source,perl]
477 ----
478 code here
479 ----
480 [] [type of markup if any]
481 [] poem
482 [] group
483 ----
484 grouped text here, actually a listing block
485 ----
486 [] alt
487 [] tables
488
489 #% notes
490 [] footnotes
491 [] [bibliography?]
492
493 #% links, linking
494 [] links - external, web, url
495 http://google.com[Google Search]
496 [] links - internal
497
498 #% images [multimedia?]
499 [] images
500 [] [base 64]
501
502 #% object numbers
503 [] ocn (object numbers)
504
505 #% contents
506 [] toc (table of contents)
507 [] index (book index)
508
509 #% breaks
510 [] line break
511 "+\n"
512 forced +
513 line break
514 [] horizontal rule
515 [] column break
516 [] page break
517
518 #% comment
519 [] comment
520 //
521
522 #% misc
523
524 [] term & definition
525 Term 1:: Definition 1
526 Term 2:: Definition 2
527 [horizontal]
528 Term 2.1;;
529 Definition 2.1
530 Term 2.2;;
531 Definition 2.2
532
533 **** TODO [#E] markdown :feature:
534
535 ***** urls
536 #% markdown
537 <http://daringfireball.net/projects/markdown/>
538 <http://daringfireball.net/projects/markdown/syntax>
539 <http://daringfireball.net/projects/markdown/basics>
540 <http://en.wikipedia.org/wiki/Markdown>
541 <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>
542 <http://whatismarkdown.com/>
543
544 Markdown supports two styles of headers, Setext and atx
545 Setext
546 <http://docutils.sourceforge.net/mirror/setext.html>
547 <http://en.wikipedia.org/wiki/Setext>
548 atx
549 <http://www.aaronsw.com/2002/atx/intro>
550
551 <http://support.iawriter.com/help/kb/general-questions/markdown-syntax-reference-guide>
552 <http://bywordapp.com/markdown/syntax.html>
553 <http://stackoverflow.com/editing-help>
554
555 <http://support.mashery.com/docs/customizing_your_portal/Markdown_Cheat_Sheet>
556 <http://warpedvisions.org/projects/markdown-cheat-sheet.md>
557 <http://nestacms.com/docs/creating-content/markdown-cheat-sheet>
558 <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>
559
560 <https://help.github.com/articles/github-flavored-markdown>
561 <http://lifehacker.com/5943320/what-is-markdown-and-why-is-it-better-for-my-to+do-lists-and-notes>
562
563 #% pandoc markdown
564 <http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html>
565 <http://johnmacfarlane.net/pandoc/README.html>
566 <http://johnmacfarlane.net/pandoc/demo/example19/Pandoc_0027s-markdown.html>
567 <http://johnmacfarlane.net/pandoc/>
568 <http://johnmacfarlane.net/pandoc/epub.html>
569 <http://johnmacfarlane.net/pandoc/faqs.html>
570
571 #% multimarkdown
572 <http://fletcher.github.io/peg-multimarkdown/>
573
574 #% markdown pandoc v multimarkdown
575 <https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown>
576
577 #% rST v markdown
578 <http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext>
579
580 ***** rb file
581 lib/sisu/v6/txt_markdown.rb
582
583 ***** transformations :transformations:markup_markdown: #%
584 #% structure - headings, levels
585 [] sisu (A-C, 1-3)
586 [] collapsed (1-6) (decoration)
587 [inline 1-5]
588 '#'
589 '##'
590 '###'
591 '####'
592 '#####'
593 '######'
594 [underscore 1-5]
595 '='
596 '-'
597 #'~'
598 #'^'
599 #'+'
600 [] node (child, parent ...)
601
602 #% font face
603 [open & close marks]
604 [] bold
605 '**'
606 [] italics
607 '*'
608 [] underscore
609 ''
610 [] superscript
611 ''
612 [] subscript
613 ''
614 [] strike
615 ''
616 [] add
617 [] monospace
618 '`'
619
620 #% para
621 [] default
622 [] indent
623 [] default, all
624 [] first line hang or indent further
625 [] bullet
626 '*'
627 [] numbered list
628 '0.'
629
630 #% blocks
631 [] code
632 ' ' #indent at least 4 spaces
633 [] [type of markup if any]
634 [] poem
635 [] group
636 [] alt
637 [] tables
638
639 #% notes
640 [] footnotes
641 [] [bibliography?]
642
643 #% links, linking
644 [] links - external, web, url
645 [] links - internal
646
647 #% images [multimedia?]
648 [] images
649 [] [base 64]
650
651 #% object numbers
652 [] ocn (object numbers)
653
654 #% contents
655 [] toc (table of contents)
656 [] index (book index)
657
658 #% breaks
659 [] line break
660 [] horizontal rule
661 (three or more asterisks hypens or underscores)
662 * * *
663 ***
664 *****
665 - - -
666 ___
667 [] column break
668 [] page break
669
670 #% misc
671
672 **** TODO [#F] rst :feature:
673
674 ***** urls
675 #% rST
676 <http://docutils.sourceforge.net/rst.html>
677 <http://docutils.sourceforge.net/docs/user/rst/quickref.html>
678 <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>
679 <http://en.wikipedia.org/wiki/ReStructuredText>
680 <http://sphinx-doc.org/rest.html>
681
682 <http://stackoverflow.com/questions/2746692/restructuredtext-tool-support>
683
684 #% rST v markdown
685 <http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext>
686
687 ***** rb file
688 lib/sisu/v6/txt_rst.rb
689
690 ***** transformations :transformations:markup_rst: #%
691 #% structure - headings, levels
692 [] sisu (A-C, 1-3)
693 [] collapsed (1-6) (decoration)
694 [inline]
695 N/A
696 [underscore]
697 Titles are underlined (or over- and underlined) with a printing
698 nonalphanumeric 7-bit ASCII character. Recommended choices are
699 "= - ` : ' " ~ ^ _ * + # < >". The underline/overline must be at
700 least as long as the title text.
701 '='
702 '-'
703 '`'
704 ':'
705 "'"
706 '"'
707
708 [] node (child, parent ...)
709
710 #% font face
711 [] bold
712 '**'
713 [] italics
714 '*'
715 [] underscore
716 '+'
717 [] superscript
718 '^'
719 [] subscript
720 [] strike
721 '-'
722 [] add
723 [] monospace
724 '``'
725
726 #% para
727 [] default
728 [] indent
729 [] default, all
730 [] first line hang or indent further
731 [] bullet
732 "-", "*" or "+"
733 '-'
734 [] numbered list
735 '#.'
736
737 #% blocks
738 [] code
739 [] [type of markup if any]
740 [] poem
741 [] group
742 [] alt
743 [] tables
744
745 #% notes
746 [] footnotes
747 [binary]
748 Footnote references, like [5]_.
749 Note that footnotes may get
750 rearranged, e.g., to the bottom of
751 the "page".
752 .. [5] A numerical footnote.
753 --
754 Autonumbered footnotes are
755 possible, like using [#]_ and [#]_.
756 .. [#] This is the first one.
757 .. [#] This is the second one.
758
759 [] [bibliography?]
760
761 #% links, linking
762 [] links - external, web, url
763 Typical result
764 External hyperlinks, like Python_.
765 .. _Python: <http://www.python.org/>
766 or
767 External hyperlinks, like `Python
768 <http://www.python.org/>`_.
769 [] links - internal
770 Internal crossreferences, like example_.
771 .. _example:
772
773 This is an example crossreference target.
774 --
775 Titles are targets, too
776 =======================
777 Implict references, like `Titles are
778 targets, too`_.
779
780 #% images [multimedia?]
781 [] images
782 [] [base 64]
783
784 #% object numbers
785 [] ocn (object numbers)
786
787 #% contents
788 [] toc (table of contents)
789 [] index (book index)
790
791 #% breaks
792 [] line break
793 [] horizontal rule
794 [] column break
795 [] page break
796
797 #% misc
798
799 **** TODO [#F] textile :feature:
800
801 ***** urls
802 #% textile
803 <http://en.wikipedia.org/wiki/Textile_(markup_language)>
804 v2.4
805 <http://www.txstyle.org/>
806 v2
807 <http://redcloth.org/hobix.com/textile/>
808
809 ***** rb file
810 lib/sisu/v6/txt_textile.rb
811
812 ***** transformations :transformations:markup_textile: #%
813 #% structure - headings, levels
814 [] sisu (A-C, 1-3)
815 [] collapsed (1-6) (decoration)
816 [inline]
817 h1(#id). An HTML first-level heading
818 h2. An HTML second-level heading
819 h3. An HTML third-level heading
820 h4. An HTML fourth-level heading
821 h5. An HTML fifth-level heading
822 h6. An HTML sixth-level heading
823 [underscore]
824 N/A
825
826 [] node (child, parent ...)
827
828 #% font face
829 [] bold
830 *bold text*
831 [] italics
832 _italic text_
833 [] underscore
834 +underlined text+
835 [] superscript
836 ^TM^
837 [] subscript
838 ~subscript~
839 [] strike
840 -strikethrough text-
841 [] add
842
843 #% para
844 [] default
845 [] indent
846 [] default, all
847 [] first line hang or indent further
848 [] bullet
849 * bulleted list
850 ** 2-level
851
852 #% blocks
853 [] code
854 [] [type of markup if any]
855 [] poem
856 [] group
857 [] alt
858 [] tables
859 |Table | with two columns |
860 |and two | rows |
861
862 #% notes
863 [] footnotes
864 Text with a link to some reference[1]
865 fn1. Footnote explanation
866 [] [bibliography?]
867
868 #% links, linking
869 [] links - external, web, url
870 "(classname)link text(title tooltip)":link_address
871 "Link to Wikipedia":http://www.wikipedia.org
872 [] links - internal
873
874 #% images [multimedia?]
875 [] images
876 !http://commons.wikimedia.org/wiki/Special:Filepath/Wikipedia-logo-en.png!
877 !imageurl(alt text)!
878 [] [base 64]
879
880 #% object numbers
881 [] ocn (object numbers)
882
883 #% contents
884 [] toc (table of contents)
885 [] index (book index)
886
887 #% breaks
888 [] line break
889 [] horizontal rule
890 [] column break
891 [] page break
892
893 #% misc
894 [] *_bold italic text_*
895 [] *-bold strikethrough text-*
896 [] *_-bold italic strikethrough text-_*
897 [] *+bold underlined text+*
898 [] *_+italic underlined text+_
899 [] *_+bold italic underlined text+_
900 [] *_-+bold italic strikethrough underlined text+-_*
901 %{font-size:18pt}font size%
902 %{color:red}text in red%
903 # Chapter 1
904
905 #% notes
906 heading inline only
907 footnotes uses marker and endnote, check
908
909 ** Improvements
910
911 *** HTML
912
913 *** XML
914
915 *** --strict mode (html w3c compliant ocn etc.)
916
917 * Code (ruby) :sisu:code:
918
919 ** code enhancements :enhance:
920
921 *** TODO [#D] directory & path, use ruby directory tools
922
923 *** TODO [#D] document url shortcut, allow addition of alternative dir stub
924 (e.g. viral Spiral)
925
926 ** code refactoring :refactor:
927
928 *** ruby 2.1
929
930 **** DONE make sure sisu works
931
932 *** TODO [#C] refactor ruby :ongoing:
933
934 ** bugs :bug:
935
936 *** misc, unclassified
937
938 **** DONE (6.0.5) [#B] sisu should give warning when part of minimal essential structure is missing :processing:fix:
939
940 work through testing for as many of these as possible
941
942 minimal content/structure requirement:
943 [metadata]
944 @title:
945 @creator:
946 [levels]
947 A~ (level A [title])
948 1~ (at least one level 1 [segment/(chapter)])
949 test what happens in the absence of each
950
951 structure rules (document heirarchy, heading levels):
952
953 there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any)
954 sisu has the fllowing levels:
955
956 A~ [title] . required (== 1) followed by B~ or 1~
957 B~ [part] * followed by C~ or 1~
958 C~ [subpart] * followed by D~ or 1~
959 D~ [subsubpart] * followed by 1~
960 1~ [segment (chapter)] + required (>= 1) followed by text or 2~
961 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~)
962 2~ [subsegment] * followed by text or 3~
963 text * followed by more text or 1~, 2~ or 3~ or relevant part, see *()
964 3~ [subsubsegment] * followed by text
965 text * followed by more text or 1~, 2~ or 3~ or relevant part, see *()
966
967 * level A~ is the tile and is mandatory
968 * there can only be one level A~
969 * heading levels BCD, are optional and there may be several of each
970 (where all three are used corresponding to e.g. Book Part Section)
971 * sublevels that are used must follow each other sequentially (alphabetically),
972 * heading levels A~ B~ C~ D~ are followed by other heading levels rather than substantive text
973 which may be the subsequent sequential (alphabetic) heading part level
974 or a heading (segment) level 1~
975 * there must be at least one heading (segment) level 1~
976 (the level on which the text is segmented, in a book would correspond to the Chapter level)
977 * additional heading levels 1~ 2~ 3~ are optional and there may be several of each
978 * heading levels 1~ 2~ 3~ are followed by text (which may be followed by the same heading level)
979 and/or the next lower numeric heading level (followed by text)
980 or indeed return to the relevant part level
981 (as a corollary to the rules above substantive text/ content
982 must be preceded by a level 1~ (2~ or 3~) heading)
983
984 there must be a title, level A
985 creator field absent: crash, no warnings given
986 title missing:
987 level A missing:
988 no level 1:
989
990 ***** NOTES/COMMENTS
991
992 revisit,
993 * check logic, add to if possible
994 * tidy, inelegant solution
995
996 **** DONE (5.3.5::6.0.5) [#B] victory chals discussed parsing problem caused by use of open-close markers around url
997
998 **** TODO UNDERWAY (6.0.5) [#B] exclude heading where possible marker '-#' not distinguished from unnumbered heading '~#'
999
1000 * ~# is general & means no ocn (for any object to which it is applied)
1001 * -# is relevant only for 1~ dummy headings & instructs that they should be
1002 removed from output where possible
1003 * where -# is used on any other objects, it is treated the same way as ~#
1004
1005 **** TODO [#B] collapsed level work out logic where dummy lev1 heading
1006
1007 * exclude heading where lev1 '-#'
1008 * means subsequent headings & text belong to parent heading (of lev1 -#) 1 level up
1009 * ponder
1010
1011
1012 **** TODO [#B] sisu 5.3.4-1 marked for autoremoval from debian testing on 2014-06-10, for depending on ruby-dbi
1013
1014 sisu 5.3.4-1 is marked for autoremoval from testing on 2014-06-10
1015 It (build-)depends on packages with these RC bugs:
1016 746081: ruby-dbi: FTBFS: ERROR: Test "ruby2.1" failed: wrong number of arguments (3 for 1..2)
1017
1018 ***** NOTES/COMMENTS
1019
1020 debian/control, remove dependency on ruby-dbi, contained in sisu-postgresql and sisu-sqlite
1021
1022 Result, status of next sisu release
1023 * sisu-sqlite works fine, depends on ruby-sqlite3
1024 * sisu-postgresql is broken till fixed to work with ruby-pg (or ruby-dbi fixed)
1025 * sample cgi search froms (cgi database query forms) are broken till
1026
1027 **** TODO [#B] sisu-postgresql, fix
1028
1029 * fix to work with ruby-pg (or if issue resolved reinstate ruby-dbi)
1030
1031 **** TODO [#B] sisu sample cgi database query forms, fix
1032
1033 * fix for sqlite3 & pg (as they currently depend on ruby-dbi)
1034
1035 *** DBT Outstanding bugs -- Normal bugs; Unclassified (2 bugs) :debian:dbt:normal:
1036 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=sisu>
1037
1038 **** DONE (5.3.5::6.0.5) [#B] #744360 [n|u] sisu: includes do not work properly :processing:fix:
1039 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744360>
1040
1041 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1042 To: Debian Bug Tracking System <submit@bugs.debian.org>
1043 Subject: includes do not work properly
1044 Date: Sun, 13 Apr 2014 12:38:59 +0200
1045 Package: sisu
1046 Version: 5.3.4-1
1047 Severity: wishlist
1048
1049 using this in foo.ssm:
1050
1051 :A~ foo
1052
1053 :B~ bar
1054
1055 << bar/baz.ssi
1056
1057 and this in baz.ssi:
1058
1059 1~ foo bar baz
1060
1061 then everything works.
1062
1063 using the more natural foo.ssm:
1064
1065 :A~ foo
1066
1067 << bar/baz.ssi
1068
1069 and baz.ssi:
1070
1071 :B~ bar
1072
1073 1~ foo bar baz
1074
1075 makes ':B~ bar' being ignored in the output (pdf) entirely.
1076
1077 Regards,
1078 Daniel
1079
1080 ***** NOTES/COMMENTS
1081
1082 it appears both give faulty text, though in different ways
1083
1084 fixed
1085
1086 **** DONE (5.3.5::6.0.5) [#B] #744378 [n|u] sisu: --no-manifest not working anymore :check:
1087 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744378>
1088
1089 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1090 To: Debian Bug Tracking System <submit@bugs.debian.org>
1091 Subject: --no-manifest not working anymore
1092 Date: Sun, 13 Apr 2014 16:12:13 +0200
1093 Package: sisu
1094 Version: 5.3.4-1
1095 Severity: wishlist
1096
1097 when running sisu-pdf with --no-manifest, the output (pdf) still
1098 contains the sisu manifest at the end of the document.
1099
1100 Regards,
1101 Daniel
1102
1103 ***** NOTES/COMMENTS
1104
1105 fix, metadata page in pdf should not contain link to manifest where --no-manifest flag is used
1106
1107 **** TODO ONGOING #746740 [n|u] manpages incomplete
1108
1109 Date: Sat, 03 May 2014 08:45:49 +0200
1110 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1111 Subject: manpages incomplete
1112 Package: sisu
1113 Version: 5.3.4-1
1114 Tag: upstream
1115 Severity: normal
1116
1117 sisu supports options like --verbose or --no-manifest, but they are not
1118 listed in the sisu manpage.
1119
1120 ***** NOTES/COMMENTS
1121
1122 documentation for sisu does lag a bit and has omissions, but I think you will
1123 find that --verbose is documented, and --no-* options are listed under --exc-*
1124 to which there is a pointer --no-manifest works but is actually
1125 --no-links-to-manifest and is listed under aliases --exc-links-to-manifest and
1126 --exc-manifest-links
1127
1128 Will leave bug open as a reminder that updating is necessary and as there are
1129 no doubt numerous issues for which this could be (re)opened
1130
1131 **** TODO #746742 [n|u] please implement --no-metadata similar to --no-manifest
1132
1133 Date: Sun, 13 Apr 2014 16:12:13 +0200
1134 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1135 Subject: --no-manifest not working anymore
1136 Package: sisu
1137 Version: 5.3.4-1
1138 Severity: wishlist
1139
1140 when running sisu-pdf with --no-manifest, the output (pdf) still
1141 contains the sisu manifest at the end of the document.
1142
1143 Regards,
1144 Daniel
1145
1146 *** DBT Outstanding bugs -- Wishlist items; Unclassified (24 bugs) :debian:dbt:wishlist:
1147
1148 **** TODO [#D] #744352 [w|u] sisu output: aligning margin numbers when using 'code'
1149 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744352>
1150
1151 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1152 To: 744352@bugs.debian.org
1153 Subject: Re: sisu output: too many margin numbers
1154 Date: Sun, 13 Apr 2014 17:27:10 +0200
1155 retitle 744352 sisu output: aligning margin numbers when using 'code'
1156 severity 744352 wishlist
1157 thanks
1158
1159 sorry, i've looked wrongly at the output, the problem is simply an
1160 aligning issue. it looks like that:
1161
1162 foo bar. [1]
1163 [2]
1164 baz
1165
1166 foo bar baz. [3]
1167
1168 rather than:
1169
1170 foo bar. [1]
1171
1172 baz [2]
1173
1174 foo bar baz. [3]
1175
1176 Regards,
1177 Daniel
1178
1179 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1180 To: Debian Bug Tracking System <submit@bugs.debian.org>
1181 Subject: too many margin numbers
1182 Date: Sun, 13 Apr 2014 12:28:14 +0200
1183 Package: sisu
1184 Version: 5.3.4-1
1185 Severity: wishlist
1186
1187 when using the following code:
1188
1189 foo bar.
1190
1191 code{
1192
1193 baz
1194
1195 }code
1196
1197 foo bar baz.
1198
1199 the result in the output (pdf) is:
1200
1201 foo bar. [1]
1202 [2]
1203 baz [3]
1204 [4]
1205 foo bar baz. [5]
1206
1207 the '[n]' designates the margin number at the right site of the page.
1208
1209 the problem is that sisu gives margin numbers to *empty* lines, which is
1210 wrong. margin numbers should only be assigned to actual content.
1211
1212 Regards,
1213 Daniel
1214
1215 ***** NOTES/COMMENTS
1216
1217 issue with pdf, look again, consider,
1218 this is cosmetic, a fix should be found, but is not striaghtforward
1219 alignment issue for code blocks not so easy to fix in some outputs, have so far ignored
1220 this is an issue with other types of text block as well
1221
1222 reason why this has not been addressed especially with code blocks:
1223 the easiest fix would be to place the numbering at the end of the first line of a code block
1224 however, as it is now, if you copy & paste a block of code you should get the code
1225 if numbering is moved down to the first line, a copy of the code block will inlcude the
1226 extraneous (to the code) object number
1227 which is to my mind a bigger problem
1228
1229 That said re pdf, LaTeX XeTeX are flexible, it may be possible to drop the ocn
1230 at the start of a code block lower on its line so that it is closer to the code
1231 that follows
1232
1233 **** DONE (6.0.5) [#D] #744353 [w|u] sisu output: please do not use typewriter for urls :output:consider:
1234 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744353>
1235
1236 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1237 To: Debian Bug Tracking System <submit@bugs.debian.org>
1238 Subject: please do not use typewriter for urls
1239 Date: Sun, 13 Apr 2014 12:28:27 +0200
1240 Package: sisu
1241 Version: 5.3.4-1
1242 Severity: wishlist
1243
1244 when using urls in sisu like this:
1245
1246 http://example.org
1247
1248 sisu then creates in the output (pdf) links like this:
1249
1250 <http://example.org>
1251
1252 where as '<http://example.org>' is written in typewriter font
1253 (monospace). please don't do that automagically since it's desturbing
1254 the visual flow when reading. If the users wants that, he should be able
1255 to configure it.
1256
1257 Regards,
1258 Daniel
1259
1260 ***** NOTES/COMMENTS
1261
1262 monospace for url outputs in pdf
1263
1264 this is default behavior of the latex url package (it uses tt typewriter font)
1265 it is possible to modify the font to sf class or tm/rm class, & I now default to sf
1266 this means when the sisu default sf is used there will be no difference in typeface,
1267 but when times roman or other is used, urls will be in sf instead of that font,
1268 (instead of the latex default typewriter)
1269
1270 it provides a visual cue even when output is monochrome, without color
1271 (and is in some way related to #744391 sisu output: no color on a4 portrait)
1272 however, it is worth noting here that urls are printed in a smaller font so as
1273 to fit more on a line of text
1274
1275 **** TODO [#C] #744354 [w|u] sisu output: please do not add '<' and '>' around urls
1276
1277 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1278 To: Debian Bug Tracking System <submit@bugs.debian.org>
1279 Subject: please do not add '<' and '>' around links
1280 Date: Sun, 13 Apr 2014 12:28:37 +0200
1281 Package: sisu
1282 Version: 5.3.4-1
1283 Severity: wishlist
1284
1285 when using urls in sisu like this:
1286
1287 http://example.org
1288
1289 sisu then creates in the output (pdf) links like this:
1290
1291 <http://example.org>
1292
1293 Please do not automagically add a '<' and '>' around urls. If the user
1294 wants them, he would add one.
1295
1296 Regards,
1297 Daniel
1298
1299 ***** NOTES/COMMENTS
1300
1301 is sisu default behavior,
1302 would need to make configurable
1303 url_visual_delimiters: '<>'
1304 look into later
1305
1306 **** DONE (5.3.5::6.0.5) [#C] #744355 [w|u] vim syntaxhighlighting: includes and directories :syntaxhi:fix:
1307 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744355>
1308
1309 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1310 To: Debian Bug Tracking System <submit@bugs.debian.org>
1311 Subject: vim syntaxhighlighting: includes and directories
1312 Date: Sun, 13 Apr 2014 12:28:46 +0200
1313 Package: sisu
1314 Version: 5.3.4-1
1315 Severity: wishlist
1316
1317 When using includes like this:
1318
1319 << foo.ssi
1320
1321 then vim correctly displays the line in blue.
1322
1323 However, when using includes in a subdirectory like this:
1324
1325 << bar/foo.ssi
1326
1327 then vim doesn't use any colors at all.
1328
1329 Regards,
1330 Daniel
1331
1332 ***** NOTES/COMMENTS
1333
1334 done
1335
1336 **** DONE PASS [#C] #744356 [w|u] vim syntaxhighlighting: urls and tags :discuss:close:
1337 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744356>
1338
1339 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1340 To: Debian Bug Tracking System <submit@bugs.debian.org>
1341 Subject: vim syntaxhighlighting: urls and tags
1342 Date: Sun, 13 Apr 2014 12:28:56 +0200
1343 Package: sisu
1344 Version: 5.3.4-1
1345 Severity: wishlist
1346
1347 When using an URL at the end of a sentence like this:
1348
1349 Foo bar baz http://example.org.
1350
1351 then vim properly highlights the url in blue.
1352
1353 this also works properly when a second sentence after it, like:
1354
1355 Foo bar baz http://example.org. Foo bar baz http://example.org.
1356
1357 it works with html tag as well, like this:
1358
1359 Foo bar baz http://example.org. <br />Foo bar baz http://example.org.
1360
1361 but it doesn't work if there's no space:
1362
1363 Foo bar baz http://example.org.<br />Foo bar baz http://example.org.
1364
1365 then, the string 'http://www.gnu.org/licenses/.<' is shown red.
1366
1367 Regards,
1368 Daniel
1369
1370 ***** NOTES/COMMENTS
1371
1372 this is meant to be flagged as an error,
1373 (red indicates error, and is an error will not parse correctly)
1374 even if the sisu parser works in the flagged case there is no promise that it will in future
1375
1376 use of angle bracket markers (html markers) in sisu markup is depreciated.
1377 for line-break use \\ instead,
1378 for which there should be surrounding spaces or a preceding space and end of line;
1379 if <br /> is still used there should be a space after the url - which sisu should remove in output.
1380
1381 would like to close without further action
1382 re-open if necessary
1383
1384 **** DONE (6.0.5) [#C] #744357 [w|u] sisu output: please create mailto links automatically
1385 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744357>
1386
1387 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1388 To: Debian Bug Tracking System <submit@bugs.debian.org>
1389 Subject: please create mailto links automatically
1390 Date: Sun, 13 Apr 2014 12:29:12 +0200
1391 Package: sisu
1392 Version: 5.3.4-1
1393 Severity: wishlist
1394
1395 When using urls like:
1396
1397 http://example.org
1398
1399 in sisu, the output (pdf) contains a hyperlink to http://example.org
1400 automatically, which is nice.
1401
1402 please also create mailto links when using email adresses like:
1403
1404 john.doe@example.org
1405
1406 Regards,
1407 Daniel
1408
1409 ***** NOTES/COMMENTS
1410
1411 for pdf fix/implement mailto links
1412 done but requires further testing & possibly refinement
1413
1414 **** DONE (6.0.5) [#C] #744358 [w|u] sisu output: please do not add ';' after \:copyright: :output:fix:
1415 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744358>
1416
1417 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1418 To: Debian Bug Tracking System <submit@bugs.debian.org>
1419 Subject: please do not add ';' after :copyright:
1420 Date: Sun, 13 Apr 2014 12:29:20 +0200
1421 Package: sisu
1422 Version: 5.3.4-1
1423 Severity: wishlist
1424
1425 When using:
1426
1427 :copyright: foo bar baz.
1428
1429 sisu generates the following in the output format (pdf):
1430
1431 foo bar baz.;
1432
1433 Please do not automagically add a semicolon (;). If the user wants a
1434 semicolon, he would add one.
1435
1436 Regards,
1437 Daniel
1438
1439 ***** NOTES/COMMENTS
1440
1441 fix copyright, remove trailing semi-colon
1442
1443 **** DONE (5.3.5::6.0.5) [#B] #744379 [w|u] sisu: missing includes doesn't give an error :processing:fix:
1444 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744379>
1445
1446 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1447 To: Debian Bug Tracking System <submit@bugs.debian.org>
1448 Subject: missing includes doesn't give an error
1449 Date: Sun, 13 Apr 2014 16:14:46 +0200
1450 Package: sisu
1451 Version: 5.3.4-1
1452 Severity: wishlist
1453
1454 When using includes (*.ssi) in a sisu master document (*.ssm) like:
1455
1456 << foo.ssi
1457
1458 and that to be included file foo.ssi (for whatever reason) doesn't
1459 exist, sisu doesn't error out but include '<< foo.ssi' literally as a
1460 string in the output (pdf).
1461
1462 Regards,
1463 Daniel
1464
1465 ***** NOTES/COMMENTS
1466
1467 5.3.4-1 writes the following to the screen:
1468 "ERROR test.ssm.sst requires invalid or non-existent file: foo.ssi"
1469
1470 and unsatisfactorily within the text output it writes no error message but the include instruction:
1471
1472 "<< foo.ssi"
1473
1474 5.3.5, the current "fix"/ solution, is to add an error message within the text rather than to stop processing with an error.
1475 In addition to (i) slightly modified (you could say corrected) to the following:
1476
1477 "ERROR test.ssm requires an invalid or non-existent file: foo.ssi"
1478
1479 the following is written within the text output:
1480
1481 "<< foo.ssi [ERROR test.ssm requires an invalid or non-existent file: foo.ssi]"
1482
1483 **** DONE (5.3.5::6.0.5) [#D] #744381 [w|u] sisu syntax: inconsistency \:copyright: and \:license: :metadata:
1484 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744381https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744381>
1485
1486 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1487 To: Debian Bug Tracking System <submit@bugs.debian.org>
1488 Subject: inconsistency between :copyright: and :license:
1489 Date: Sun, 13 Apr 2014 16:26:55 +0200
1490 Package: sisu
1491 Version: 5.3.4-1
1492 Severity: wishlist
1493
1494 when using ':copyright: foo', then the output contains 'foo'.
1495
1496 when using ':license: foo', then the output contains 'License: foo'.
1497
1498 this is inconsistent. either both should have a 'prefix' in the output,
1499 or neither should have one (i'd prefere the latter).
1500
1501 Regards,
1502 Daniel
1503
1504 ***** NOTES/COMMENTS
1505
1506 Under rights there are a series of sub-categories starting with copyright, that
1507 need to be distinguished. Until now started distinguishing after after
1508 Copyright. For consistency have add the prefix 'Copyright' to the output.
1509 Preference to omit noted, but this solution is consistent with options
1510 provided. Bug closed, re-open if necessary.
1511
1512 **** DONE (6.0.5) [#B] #744383 [w|u] sisu syntax: :B and :C result in the same formatting :output:fix: (partial solution)
1513 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744383>
1514
1515 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1516 To: Debian Bug Tracking System <submit@bugs.debian.org>
1517 Subject: sisu syntax: :B and :C result in the same formatting
1518 Date: Sun, 13 Apr 2014 16:32:07 +0200
1519 Package: sisu
1520 Version: 5.3.4-1
1521 Severity: wishlist
1522
1523 when using :A, :B, and :C in sisu, in the output (pdf) both :B and :C
1524 are formatted identically.
1525
1526 imho :C should be 'smaller' than :B.
1527
1528 or, as an analogy with html: i would expect that :A equals <h1>, :B
1529 equals <h2>, and :C equals <h3>. currently, (in that analogy), :B and :C
1530 both equal <h2>.
1531
1532 Regards,
1533 Daniel
1534
1535 ***** NOTES/COMMENTS
1536
1537 this is in part an artifact of LaTeX not having as many document heading levels
1538 and trying to take advantage of the behavior of existing levels rather than
1539 customizing further
1540
1541 look for a solution, possibly overriding the default font sizes for each
1542
1543 The current settings were chosen because, there are not enough levels and I
1544 find too many different font sizes disconcerting, especially running sisu over
1545 a wide variety of document types
1546
1547 the following levels are available in LaTeX
1548
1549 \part
1550 \chapter
1551 \section
1552 \subsection
1553 \subsubsection
1554
1555 the levels in sisu are
1556
1557 A [title]
1558 B [part]
1559 C [subpart]
1560 D [subsubpart]
1561 1 [segment (chapter)]
1562 2 [subsegment]
1563 3 [subsubsegment]
1564
1565 sisu current mapping:
1566
1567 level A [title]
1568 level B C D \part (it is up to the user to make part levels visually distinguishable e.g. Book Part Section)
1569 [skipped \chapter]
1570 [skipped \section]
1571 level 1 \subsection
1572 level 2 \subsubsection
1573 level 3 \subsubsection
1574
1575 the reason for skipping section was the default configuration and resulting
1576 fact that it made for a table of contents that takes more space
1577
1578 sisu new mapping:
1579
1580 level A [title]
1581 level B C D \part (it is up to the user to make part levels visually distinguishable e.g. Book Part Section)
1582 [skipped \chapter]
1583 level 1 \section
1584 level 2 \subsection
1585 level 3 \subsubsection
1586
1587 levels B C & D are the same size,
1588 it is up to the user to make part levels visually distinguishable
1589 e.g. Book Part Section
1590 levels 1 2 & 3 are now distinguished
1591
1592 (Closes #744386) sisu syntax: 1~ and 2~ result in the same formatting
1593 (under consideration & yet to be done #744383) sisu syntax: :B and :C result in the same formatting
1594 (touches )
1595 override part font size settings for different levels (B C D)
1596
1597 **** TODO [#C] #744384 [w|u] sisu syntax: relies on empty lines
1598 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744384>
1599
1600 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1601 To: Debian Bug Tracking System <submit@bugs.debian.org>
1602 Subject: sisu syntax: relies on empty lines
1603 Date: Sun, 13 Apr 2014 16:34:46 +0200
1604 Package: sisu
1605 Version: 5.3.4-1
1606 Severity: wishlist
1607
1608 the following snipped:
1609
1610 :C~ foo bar
1611 << foo-bar.ssi
1612
1613 means that the include is ignored entirely. apparently sisu relies on
1614 having an empty line in between like this:
1615
1616 :C~ foo bar
1617
1618 << foo-bar.ssi
1619
1620 Regards,
1621 Daniel
1622
1623 ***** NOTES/COMMENTS
1624
1625 consider,
1626
1627 (i) as a general observation, sisu relies on emptly lines to identify separate objects
1628 such as headings, paragraphs (and indeed insertions)
1629
1630 (ii) a heading need not be on a single line (so << would be part of that heading)
1631 this means sisu should be able to work identifying headings in wrapped texts
1632 (e.g. where the text is wrapped at 80 and the heading is longer than that)
1633
1634 there has been no rule to the contrary (i.e. that headings should be on a single text line)
1635
1636 consider, should there be such a rule?
1637
1638 **** DONE (6.0.5) [#B] #744386 [w|u] sisu syntax: 1~ and 2~ result in the same formatting :output:pdf:fix: (see #744383)
1639 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744386>
1640
1641 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1642 To: Debian Bug Tracking System <submit@bugs.debian.org>
1643 Subject: sisu syntax: 1~ and 2~ result in the same formatting
1644 Date: Sun, 13 Apr 2014 16:43:51 +0200
1645 Package: sisu
1646 Version: 5.3.4-1
1647 Severity: wishlist
1648
1649 similar as with #744383, the same also applies for 1~ and 2~ - they
1650 should be different in the output format (pdf here).
1651
1652 Regards,
1653 Daniel
1654
1655 ***** NOTES/COMMENTS
1656
1657 1~ 2~ 3~ are now differentiated
1658
1659 deal with under #744383
1660
1661 **** TODO [#B] #744390 [w|u] sisu: empty sections are ignored
1662 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744390>
1663
1664 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1665 To: Debian Bug Tracking System <submit@bugs.debian.org>
1666 Subject: sisu: empty sections are ignored
1667 Date: Sun, 13 Apr 2014 17:09:32 +0200
1668 Package: sisu
1669 Version: 5.3.4-1
1670 Severity: wishlist
1671
1672 if you have the following sisu syntax:
1673
1674 :B~ foo
1675
1676 1~ foo1
1677
1678 foo1.
1679
1680 1~ foo2
1681
1682 foo2.
1683
1684 :B~ bar
1685
1686 1~ bar1
1687
1688 1~ bar2
1689
1690 :B~ baz
1691
1692 1~ baz1
1693
1694 1~ baz2
1695
1696 then anything (including and) after ':B~ bar' is ignored entirely.
1697
1698 ***** NOTES/COMMENTS
1699
1700 further info, have not yet been able to duplicate,
1701 seemed to work (checked pdf & html (scroll & seg))
1702 was not able to reproduce
1703 will look again
1704
1705 **** DONE (6.0.5) [#C] #744391 [w|u] sisu output: no color on a4 portrait :output:pdf:contemplate:
1706 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744391>
1707
1708 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1709 To: Debian Bug Tracking System <submit@bugs.debian.org>
1710 Subject: sisu output: please use (blue) color for links
1711 Date: Sun, 13 Apr 2014 17:23:37 +0200
1712 Package: sisu
1713 Version: 5.3.4-1
1714 Severity: wishlist
1715 Tags: upstream
1716
1717 it would be nice if links (urls and emails) would be colored blue to
1718 mark them visually as links. this behaviour is somewhat the lowest
1719 common denominator in browsers (if you use html without any css that is).
1720
1721 Regards,
1722 Daniel
1723
1724 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1725 To: 744391@bugs.debian.org
1726 Subject: Re: sisu output: please use (blue) color for links
1727 Date: Sun, 13 Apr 2014 17:35:33 +0200
1728 retitle 744391 sisu output: no color on a4 portrait
1729 thanks
1730
1731 now this is strange.. turns out that (yes, i have colors enabled in
1732 sisurc) the portrait a4 pdf has no colors at all, while the landscape a4
1733 pdf does indeed have colors (red for toc, blue for links).
1734
1735 Regards,
1736 Daniel
1737
1738 ***** NOTES/COMMENTS
1739
1740 background:
1741 portrait was provided for print/paper copy and is great for that in monochrome
1742 (without grays for colored links),
1743 landscape better matching a screen for visual presentations, color affecting the landscape only
1744
1745 solution:
1746 make configurable by cli & rc file
1747 make both (portrait & landscape colors) configurable
1748 either as hyperlinks monochrome or colored
1749 overriding existing default which remains as described
1750
1751 document
1752 cli:
1753 --pdf-hyperlinks-no-color or --pdf-hyperlinks-mono
1754 --pdf-hyperlinks-color
1755
1756 rc:
1757
1758 default:
1759 pdf_hyperlinks: *[possible values]
1760 pdf_hyperlinks_portrait: *[possible values]
1761 pdf_hyperlinks_landscape: *[possible values]
1762
1763 * 'color' or ('mono' or 'no-color' or 'color-off')
1764
1765 **** TODO [#D] #744395 [w|u] sisu output: half-page title page in landscape output
1766 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744395>
1767
1768 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1769 To: Debian Bug Tracking System <submit@bugs.debian.org>
1770 Subject: sisu output: half-page title page in landscape output
1771 Date: Sun, 13 Apr 2014 17:38:03 +0200
1772 Package: sisu
1773 Version: 5.3.4-1
1774 Severity: wishlist
1775 Tags: upstream
1776
1777 in a4 landscape output, there's always two pages on one page, which is
1778 nice; except for the title page which spans over the whole page.
1779
1780 it would be nice if the first page would be consistent to the same
1781 scheme like the rest of the document - spanning only over the half of
1782 the page.
1783
1784 Regards,
1785 Daniel
1786
1787 ***** NOTES/COMMENTS
1788
1789 think about, should be fairly easily done, but am reluctant
1790
1791 note the page numbering in landscape, the two landscape columns are given a single page number
1792 it is really a landscape two column per-page text, provided primarily for screen viewing or
1793 other convenience if found
1794
1795 (many viewers provide two page per screen presentations, which would result in an effect similar to the one requested
1796 the issue I guess might arise in that they are not printable on a single page? ...
1797 but then the current settings are arguably justified)
1798
1799 **** TODO [#C] #744396 [w|u] sisu output: "european" toc indenting
1800 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744396>
1801
1802 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1803 To: Debian Bug Tracking System <submit@bugs.debian.org>
1804 Subject: sisu output: "european" toc indenting
1805 Date: Sun, 13 Apr 2014 17:40:53 +0200
1806 Package: sisu
1807 Version: 5.3.4-1
1808 Severity: wishlist
1809 Tags: upstream
1810
1811 by default, latex uses the following indenting in the TOC:
1812
1813 1. foo
1814 1.1 bar1
1815 1.1.1 baz
1816 1.2 bar2
1817
1818 there's a latex option that i don't remember off-hand to have the
1819 indenting like it's common in europe:
1820
1821 1. foo
1822 1.1 bar1
1823 1.1.1 baz
1824 1.2 bar2
1825
1826 it would be nice if sisu could let the used decide which indenting style
1827 to use for TOCs.
1828
1829 Regards,
1830 Daniel
1831
1832 ***** NOTES/COMMENTS
1833
1834 will look at: should be possible; requires a configuration option
1835
1836 **** DONE (6.0.5) [#B] #744399 [w|u] sisu syntax: :A smaller formatted than :B :output:fix: (see #744383) (partial solution)
1837 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744399>
1838
1839 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1840 To: Debian Bug Tracking System <submit@bugs.debian.org>
1841 Subject: sisu syntax: :A smaller formatted than :B
1842 Date: Sun, 13 Apr 2014 17:49:26 +0200
1843 Package: sisu
1844 Version: 5.3.4-1
1845 Severity: wishlist
1846 Tags: upstream
1847
1848 in a document like this:
1849
1850 :A~ foo
1851
1852 :B~ bar
1853
1854 the :A~ 'title' is formated 'smaller' (not bold, smaller font size) than
1855 the :B~ 'title' on the first page of the actual document (means, first
1856 page after TOC).
1857
1858 Regards,
1859 Daniel
1860
1861 ***** NOTES/COMMENTS
1862
1863 for pdf
1864
1865 now is same size see #744383
1866
1867 \part (level A B C D)
1868 \chapter (skipped)
1869 \section (level 1)
1870 \subsection (level 2)
1871 \subsubsection (level 3)
1872
1873 **** DONE (6.0.5) [#C] #744402 [w|u] sisu: support sha512 :implement:
1874 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744402>
1875
1876 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1877 To: Debian Bug Tracking System <submit@bugs.debian.org>
1878 Subject: sisu: support sha512
1879 Date: Sun, 13 Apr 2014 18:06:56 +0200
1880 Package: sisu
1881 Version: 5.3.4-1
1882 Severity: wishlist
1883 Tags: upstream
1884
1885 sisu uses sha256 when using sha as digest, please support sha512.
1886
1887 it would be even nicer if you could specify the actual digest like
1888 'sha512', 'sha256', etc. rather than just 'sha'.
1889
1890 Regards,
1891 Daniel
1892
1893 ***** NOTES/COMMENTS
1894
1895 implemented
1896 document command line option --sha512
1897
1898 **** DONE (6.0.5) [#C] #744405 [w|u] sisu: set default font size :configuration:pdf:implement:
1899 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744405>
1900
1901 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1902 To: Debian Bug Tracking System <submit@bugs.debian.org>
1903 Subject: sisu: set default font size
1904 Date: Sun, 13 Apr 2014 18:29:46 +0200
1905 Package: sisu
1906 Version: 5.3.4-1
1907 Severity: wishlist
1908 Tags: upstream
1909
1910 in sisurc, one can set the default fonts. it would be nice to be also
1911 able to set the default font size.
1912
1913 Regards,
1914 Daniel
1915
1916 ***** NOTES/COMMENTS
1917
1918 for pdf make configurable
1919
1920 yaml.rc
1921
1922 default:
1923 texpdf_fontsize: 12
1924
1925 command-line
1926
1927 --pdf-fontsize-12
1928 --pdf-fontsize-8
1929 etc.
1930
1931 **** TODO [#C] #744407 [w|u] sisu: possibility to influence content/formating of the title page
1932 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744407>
1933
1934 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1935 To: Debian Bug Tracking System <submit@bugs.debian.org>
1936 Subject: sisu: possibility to influence content/formating of the title page
1937 Date: Sun, 13 Apr 2014 18:32:14 +0200
1938 Package: sisu
1939 Version: 5.3.4-1
1940 Severity: wishlist
1941 Tags: upstream
1942
1943 by default, the title page (in the pdf output) shows @title and @creator.
1944
1945 it would be nice if there would be a possibility to influence the
1946 formatting (e.g. to have the title written in bold), and to have
1947 additional possibilities to influence the content on the title page
1948 (like the date or version, an url, or other text strings).
1949
1950 Regards,
1951 Daniel
1952
1953 ***** NOTES/COMMENTS
1954
1955 consider, work on possibly, later
1956
1957 **** TODO [#C] #744408 [w|u] sisu: support more than one level of includes/nested includes
1958 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744408>
1959
1960 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
1961 To: Debian Bug Tracking System <submit@bugs.debian.org>
1962 Subject: sisu: support more than one level of includes/nested includes
1963 Date: Sun, 13 Apr 2014 18:39:23 +0200
1964 Package: sisu
1965 Version: 5.3.4-1
1966 Severity: wishlist
1967 Tags: upstream
1968
1969 currently, it's possible to use only one ssm file which itself includes
1970 one or more ssi files.
1971
1972 it would be nice if the ssm could include an 'intermediate' ssi, which
1973 then includes further ssi files. this is very handy for larger documents.
1974
1975 Regards,
1976 Daniel
1977
1978 ***** NOTES/COMMENTS
1979
1980 consider,
1981 I have to date deliberately tried to keep it easy to follow documents & not have too much depth ...
1982 The idea of recursive includes is un-attractive (messy for a document)
1983
1984 .ssm currently can contain .sst or .ssi
1985 .sst files can be processed independently,
1986 .ssi files are only insertions & cannot
1987
1988 allowing .ssi to also include other .ssi or .sst could lead to recursive .ssi
1989 allowing .ssm to also include other .ssm .ssi or .sst could lead to recursive .ssm
1990
1991 stopping after an additional level of includes seems arbitrary, and possibly prone to error if you are dealing with many documents
1992
1993 a possibility would be to have another file extension to flag the role of the file,
1994 .ssmi (not very attractive) might do it
1995 (providing visual cue signalling its role as both a master file and an insertion/included file that cannot be processed independently)
1996 a .ssmi file must be included in a .ssm file
1997 a .ssmi file (like .ssm) permits the inclusion only of .sst or .ssi files
1998
1999 will work on eventually
2000
2001 **** TODO [#C] #744409 [w|u] sisu output: urls in code blocks are not linkified
2002 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744409>
2003
2004 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
2005 To: Debian Bug Tracking System <submit@bugs.debian.org>
2006 Subject: sisu output: urls in code blocks are not linkified
2007 Date: Sun, 13 Apr 2014 18:41:09 +0200
2008 Package: sisu
2009 Version: 5.3.4-1
2010 Severity: wishlist
2011 Tags: upstream
2012
2013 it would be nice if urls written withiin code{...}code blocks would also
2014 be automatically transformed into a link within the output (html).
2015
2016 Regards,
2017 Daniel
2018
2019 ***** NOTES/COMMENTS
2020
2021 consider, so far code blocks are pretty much untouched ... not tampered with,
2022 this could be done though
2023
2024 **** DONE (6.0.5) [#C] #744541 [w|u] sisu: urls in @creator broken
2025 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744541>
2026
2027 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
2028 To: Debian Bug Tracking System <submit@bugs.debian.org>
2029 Subject: sisu: urls in @creator broken
2030 Date: Sun, 13 Apr 2014 18:45:35 +0200
2031 Package: sisu
2032 Version: 5.3.4-1
2033 Severity: wishlist
2034 Tags: upstream
2035
2036 first, if you have an url within @creator, like:
2037
2038 @creator: foo bar http://example.org
2039
2040 the generation fails (pdf output).
2041
2042 as a workaround, i put the url into parenthesis, like:
2043
2044 @creator: foo bar (http://example.org)
2045
2046 but then, it would be nice if that url would be automatically
2047 transformed into a link in the output format (pdf).
2048
2049 Regards,
2050 Daniel
2051
2052 ***** NOTES/COMMENTS
2053
2054 pdf, fix
2055
2056 **** TODO [#C] #744685 [w|u] sisu output: copy&past-able wrapped code blocks
2057 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744685>
2058
2059 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
2060 To: Debian Bug Tracking System <submit@bugs.debian.org>
2061 Subject: sisu output: copy&past-able wrapped code blocks
2062 Date: Sun, 13 Apr 2014 19:04:01 +0200
2063 Package: sisu
2064 Version: 5.3.4-1
2065 Severity: wishlist
2066 Tags: upstream
2067
2068 if a line within a 'code{...}code' block is longer and needs to be
2069 wrapped, sisu indicates the wrapping with an 'arrow' (←) symbol, which
2070 is nice.
2071
2072 it would be even nicer if the arrow would not 'selectable', so that when
2073 you mark the line spanning over two lines with your mouse, the arrow is
2074 not selected and thus not copy&pasted.
2075
2076 i don't know how to do this, but it's possible within pdfs, as can be
2077 seen in lots of pdfs in the internet.
2078
2079 Regards,
2080 Daniel
2081
2082 ***** NOTES/COMMENTS
2083
2084 find out how and implement, further feedback on appropriate xetex tools welcome
2085
2086 [Note: if can be applied to random characters, use may be of interest for
2087 object numbers as well!]
2088
2089 **** TODO [#C] #744734 [w|u] sisu output: replace all occurences of (C) rather than the first only
2090
2091 From: Daniel Baumann <daniel.baumann@progress-technologies.net>
2092 To: Debian Bug Tracking System <submit@bugs.debian.org>
2093 Subject: sisu output: replace all occurences of (C) rather than the first only
2094 Date: Mon, 14 Apr 2014 06:11:13 +0200
2095
2096 Package: sisu
2097 Version: 5.3.4-1
2098 Severity: wishlist
2099 Tags: upstream
2100
2101 if you have a '(C)' in :copyright:, it is automatically replaced with a
2102 copyright symbol, which is nice, however, it sisu does that with the
2103 first occurence only.
2104
2105 so if you use:
2106
2107 :copyright: (C) john doe<br />(C) jane doe
2108
2109 then the second occurence is not replaced and that combination looks
2110 very ugly. i suggest you replace all occurences of '(C)' to the
2111 copyright symbol automatically.
2112
2113 Regards,
2114 Daniel