diff options
Diffstat (limited to 'data/doc/sisu/sisu.org')
-rw-r--r-- | data/doc/sisu/sisu.org | 1546 |
1 files changed, 0 insertions, 1546 deletions
diff --git a/data/doc/sisu/sisu.org b/data/doc/sisu/sisu.org deleted file mode 100644 index a5f8dbdc..00000000 --- a/data/doc/sisu/sisu.org +++ /dev/null @@ -1,1546 +0,0 @@ -#+PRIORITIES: A F E -(emacs:evil mode gifts a "vim" of "alternative" powers! ;) - -* General -** Finding -*** source - -http://git.sisudoc.org/gitweb/ - -sisu git repo: -http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary - -sisu-markup-samples git repo: -http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary - -*** mailing list -sisu at lists.sisudoc.org - -http://lists.sisudoc.org/listinfo/sisu - -** irc oftc sisu - -** home pages - * <http://www.sisudoc.org/> - * <http://search.sisudoc.org/> - * <http://www.jus.uio.no/sisu> - -** Installing sisu - -*** where you take responsibility for having the correct dependencies - -Provided you have *Ruby*, *SiSU* can be run. - -SiSU should be run from the directory containing your sisu marked up document -set. - -This works fine so long as you already have sisu external dependencies in -place. For many operations such as html, epub, odt this is likely to be fine. -Note however, that additional external package dependencies, such as texlive -(for pdfs), sqlite3 or postgresql (for search) should you desire to use them -are not taken care of for you. - -**** run off the source tarball without installation - -RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) -.......................................................... - -***** 1. Obtain the latest sisu source - -using git: - -http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary -http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log - - git clone git://git.sisudoc.org/git/code/sisu.git - -or, identify latest available source: - -https://packages.debian.org/sid/sisu -http://packages.qa.debian.org/s/sisu.html -http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org - -http://sisudoc.org/sisu/archive/pool/main/s/sisu/ - -and download the: - - sisu_5.4.5.orig.tar.xz - -using debian tool dget: - -The dget tool is included within the devscripts package -https://packages.debian.org/search?keywords=devscripts -to install dget install devscripts: - - apt-get install devscripts - -and then you can get it from Debian: - dget -xu http://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc - -or off sisu repos - dget -x http://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc -or - dget -x http://sisudoc.org/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc - -***** 2. Unpack the source - -Provided you have *Ruby*, *SiSU* can be run without installation straight from -the source package directory tree. - -Run ruby against the full path to bin/sisu (in the unzipped source package -directory tree). SiSU should be run from the directory containing your sisu -marked up document set. - - ruby ~/sisu-5.4.5/bin/sisu --html -v document_name.sst - -This works fine so long as you already have sisu external dependencies in -place. For many operations such as html, epub, odt this is likely to be fine. -Note however, that additional external package dependencies, such as texlive -(for pdfs), sqlite3 or postgresql (for search) should you desire to use them -are not taken care of for you. - -**** gem install (with rake) - -(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install -the gem - -Provided you have ruby & rake, this can be done with the single command: - - rake gem_create_build_install - -to build and install sisu v5 & sisu v6, alias gemcbi - -separate gems are made/installed for sisu v5 & sisu v6 contained in source. - -to build and install sisu v5, alias gem5cbi: - - rake gem_create_build_install_stable - -to build and install sisu v6, alias gem6cbi: - - rake gem_create_build_install_unstable - -for individual steps (create, build, install) see rake options, rake -T to -specify sisu version for sisu installed via gem - - gem search sisu - - sisu _5.4.5_ --version - - sisu _6.0.11_ --version - -to uninstall sisu installed via gem - - sudo gem uninstall --verbose sisu - -For a list of alternative actions you may type: - - rake help - - rake -T - -Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> - -**** installation with setup.rb - -this is a three step process, in the root directory of the unpacked *SiSU* as -root type: - -ruby setup.rb config -ruby setup.rb setup -#[as root:] -ruby setup.rb install - -further information: -<http://i.loveruby.net/en/projects/setup/> -<http://i.loveruby.net/en/projects/setup/doc/usage.html> - - ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install - -*** Debian install - -*SiSU* is available off the *Debian* archives. It should necessary only to run -as root, Using apt-get: - - apt-get update - - apt get install sisu-complete - -(all sisu dependencies should be taken care of) - -If there are newer versions of *SiSU* upstream, they will be available by -adding the following to your sources list /etc/apt/sources.list - -#/etc/apt/sources.list - -deb http://www.jus.uio.no/sisu/archive unstable main non-free -deb-src http://www.jus.uio.no/sisu/archive unstable main non-free - -The non-free section is for sisu markup samples provided, which contain -authored works the substantive text of which cannot be changed, and which as a -result do not meet the debian free software guidelines. - -*SiSU* is developed on *Debian*, and packages are available for *Debian* that -take care of the dependencies encountered on installation. - -The package is divided into the following components: - - *sisu*, the base code, (the main package on which the others depend), without - any dependencies other than ruby (and for convenience the ruby webrick web - server), this generates a number of types of output on its own, other - packages provide additional functionality, and have their dependencies - - *sisu-complete*, a dummy package that installs the whole of greater sisu as - described below, apart from sisu -examples - - *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated - - *sisu-postgresql*, dependencies used by sisu to populate postgresql database - (further configuration is necessary) - - *sisu-sqlite*, dependencies used by sisu to populate sqlite database - - *sisu-markup-samples*, sisu markup samples and other miscellany (under - *Debian* Free Software Guidelines non-free) - - *SiSU* is available off Debian Unstable and Testing [link: - <http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>] - [^1] install it using apt-get, aptitude or alternative *Debian* install tools. - -* Markup :sisu:markup: - -** sisu - -#% structure - headings, levels - * headings (A-D, 1-3) - * inline - 'A~ ' NOTE title level - 'B~ ' NOTE optional - 'C~ ' NOTE optional - 'D~ ' NOTE optional - '1~ ' NOTE chapter level - '2~ ' NOTE optional - '3~ ' NOTE optional - '4~ ' NOTE optional :consider: - * node - * parent - * children - -#% font face NOTE open & close marks, inline within paragraph - * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold - * bold '!{ ... }!' - * italics '/{ ... }/' - * underscore '_{ ... }_' - * superscript '^{ ... }^' - * subscript ',{ ... },' - * strike '-{ ... }-' - * add '+{ ... }+' - * monospace '#{ ... }#' -#% para NOTE paragraph controls are at the start of a paragraph - * a para is a block of text separated from others by an empty line - * indent - * default, all '_1 ' up to '_9 ' - * first line hang '_1_0 ' - * first line indent further '_0_1 ' - * bullet - [levels 1-6] - '_* ' - '_1* ' - '_2* ' - * numbered list - [levels 1-3] - '# ' - -#% blocks NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be - * code - * [type of markup if any] - * poem - * group - * alt - * tables -#% boxes - NOTE grouped text with code block type color & possibly default image, warning, tip, red, blue etc. decide [NB N/A not implemented] - -#% notes NOTE inline within paragraph at the location where the note reference is to occur - * footnotes '~{ ... }~' - * [bibliography] [NB N/A not implemented] - -#% links, linking - * links - external, web, url - * links - internal - -#% images [multimedia?] - * images - * [base64 inline] [N/A not implemented] - -#% object numbers - * ocn (object numbers) - automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided) - -#% contents - * toc (table of contents) - autogenerated from structure/headings information - * index (book index) - built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text - -#% breaks - * line break ' \\ ' inline - * page break, column break ' -\\- ' start of line, breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. - * page break, page new ' =\\= ' start of line, breaks the page, starts a new page. - * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs) - -#% book type index - -#% comment - * comment - -#% misc - * term & definition - -** proposals/additions - -*** TODO [#B] markup syntax code block, indicate syntax of code :feature: - ``` code:ruby - -*** TODO [#C] colored boxes round text :feature:ponder: - ``` box:red (select color of box) - ``` box:warn ``` box:tip (some default boxes? decide) - ``` box:red:"Warn" (select color and lead text of box, else instead - select color box & use regular single line bold markup ^!_ Warn$) - -*** TODO [#D] blockquotes implement? :feature:ponder: - ``` quote - not sure how best to represent - -*** TODO [#D] bibliography :feature:ponder: - -*** TODO speaker, as e.g. play (irc?) :feature:ponder: - ``` Ophelia: - ::Ophelia - -*** TODO [#F] time stamp (e.g. for irc, video text?):feature:ponder: - ``` 04:03 - ``` 04:03 ... 07:12 - ``` 04:03 + 03:09 - ``` 12:04:03 - ``` 12:04:03 ... 12:07:12 - ``` 12:04:03 + 03:09 - probably not worth the effort, as time stamp is an alternative - identifying number (to ocn, and ∴ sisu objects not ideal) - -*** TODO book index, alternative based on search within text - -** syntax hilighting - -*** vim -data/sisu/conf/editor-syntax-etc/vim/ -data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim - -*** emacs -data/sisu/conf/editor-syntax-etc/emacs/ -data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el - -* Document Abstraction :sisu:doc_abstr: - -** TODO [#D] XML middle layer? - -*** XMLda sisu - consder alternative sisu layer in XML - -*** TODO [#D] RelaxNG sisu - -* Output :sisu:output: - -** New outputs to consider - -*** XML :xml: -%% xml, docbook.txt fictionbook.txt xldl.txt lml.txt tei.txt emacs.txt -<http://xml.silmaril.ie/> -<http://www.xml.com/> -<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> - -<http://broadcast.oreilly.com/2012/03/xmls-dialect-problem.html> - -xml editor vim emacs -<http://chimera.labs.oreilly.com/books/1234000000058/ch01.html#which_xml_editor_should_i_use> -nXML plugin -<http://blog.tommorris.org/post/2456183251/emacs-and-nxml-survival-guide> -<http://johnbokma.com/mexit/2008/10/01/nxml-emacs-how-to.html> -<http://www.emacswiki.org/cgi-bin/wiki/NxmlModeForXHTML> -<http://www.xmlhack.com/read.php_item=2061> -<http://infohost.nmt.edu/tcc/help/pubs/nxml/index.html> -emacs.txt evil.txt - -<http://www.oreillynet.com/xml/blog/2005/10/smart_quotes_and_more_in_vim_a.html> -<http://stackoverflow.com/questions/1430164/differences-between-emacs-and-vim> - -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 -<http://www.docbook.org> -<http://www.sagehill.net/docbookxsl/index.html> -<http://wiki.docbook.org/> -<http://www.docbook.org/tdg5/en/html/> -<http://www.docbook.org/tdg5/en/html/docbook.html> -<http://www.docbook.org/tdg5/en/html/ch01.html> -<http://www.docbook.org/tdg5/en/html/ch02.html> -<http://www.sagehill.net/docbookxsl/index.html> - -<http://www.docbook.org/schemas/5x> -<http://www.docbook.org/xml/5.0/> - -<http://infohost.nmt.edu/tcc/help/pubs/docbook5/web/index.html> - -<http://docbook.org/xml/5.0/rng/docbook.rng> -<http://docbook.org/xml/5.0/rng/docbook.rnc> - -<http://www.cuddletech.com/blog/pivot/entry.php?id=509> - -***** 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 - <http://www.docbook.org/tdg5/en/html/literallayout.html> - [] 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) - <http://www.docbook.org/tdg5/en/html/toc.html> - [] index (book index) - -#% misc - -**** TODO [#D] fictionbook :feature: - -***** urls -#% fictionbook xml.txt -<http://en.wikipedia.org/wiki/FictionBook> -<http://fictionbook.org/index.php/Eng:FictionBook> -<http://fictionbook.org/index.php/Eng:Articles> -<http://fictionbook.org/index.php/Eng:Documentations> -<http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1> -<http://www.fictionbook.org/index.php/Eng:FictionBook> -<http://fictionbook-lib.org/> -<http://fictionbook-lib.org/browse.php> -<http://wiki.mobileread.com/wiki/FB2> - -***** 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 - -<http://en.wikipedia.org/wiki/FictionBook> -<http://fictionbook.org/index.php/Eng:FictionBook> -<http://fictionbook.org/index.php/Eng:Articles> -<http://fictionbook.org/index.php/Eng:Documentations> -<http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1> -<http://www.fictionbook.org/index.php/Eng:FictionBook> - -<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> - -<https://addons.mozilla.org/en-US/firefox/addon/fb2-reader/> - -**** 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 -<http://www.ister.org/code/xldl/> -<http://www.ister.org/code/xldl/doc/xldl.dtd.html> -<line> <stanza> - -**** TODO [#E] Literature Markup Language - <LML /> :feature: - -***** urls -%% Literature Markup Language - <LML /> -<http://hoffmann.bplaced.net/lml/> -"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 - <LML /> 1.1 -<http://hoffmann.bplaced.net/lml/lml1.1.php> - -**** TODO [#E] TEI Lite (Text Encoding Initiative) :feature: - -***** urls -%% TEI Lite (Text Encoding Initiative) -<http://www.tei-c.org/Guidelines/Customization/Lite/> -<http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_lite.doc.html> - -*** Text :txt: - -sisu_markup.txt asciidoc.txt markdown.txt textile.txt rst.txt - -**** TODO [#D] asciidoc :feature: - -***** urls -#% asciidoc -<http://asciidoc.org/> -<http://asciidoctor.org/> -<http://www.methods.co.nz/asciidoc/> -<http://en.wikipedia.org/wiki/AsciiDoc> - -cheatsheets -<http://powerman.name/doc/asciidoc> -<http://powerman.name/doc/asciidoc-index> - -<http://www.methods.co.nz/asciidoc/asciidoc.txt> -<http://www.methods.co.nz/asciidoc/userguide.html> - -<http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html> -<http://www.methods.co.nz/asciidoc/asciidoc.html> -<http://www.methods.co.nz/asciidoc/chunked/index.html> - -***** 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 -<http://daringfireball.net/projects/markdown/> -<http://daringfireball.net/projects/markdown/syntax> -<http://daringfireball.net/projects/markdown/basics> -<http://en.wikipedia.org/wiki/Markdown> -<https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> -<http://whatismarkdown.com/> - -Markdown supports two styles of headers, Setext and atx -Setext -<http://docutils.sourceforge.net/mirror/setext.html> -<http://en.wikipedia.org/wiki/Setext> -atx -<http://www.aaronsw.com/2002/atx/intro> - -<http://support.iawriter.com/help/kb/general-questions/markdown-syntax-reference-guide> -<http://bywordapp.com/markdown/syntax.html> -<http://stackoverflow.com/editing-help> - -<http://support.mashery.com/docs/customizing_your_portal/Markdown_Cheat_Sheet> -<http://warpedvisions.org/projects/markdown-cheat-sheet.md> -<http://nestacms.com/docs/creating-content/markdown-cheat-sheet> -<https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> - -<https://help.github.com/articles/github-flavored-markdown> -<http://lifehacker.com/5943320/what-is-markdown-and-why-is-it-better-for-my-to+do-lists-and-notes> - -#% pandoc markdown -<http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html> -<http://johnmacfarlane.net/pandoc/README.html> -<http://johnmacfarlane.net/pandoc/demo/example19/Pandoc_0027s-markdown.html> -<http://johnmacfarlane.net/pandoc/> -<http://johnmacfarlane.net/pandoc/epub.html> -<http://johnmacfarlane.net/pandoc/faqs.html> - -#% multimarkdown -<http://fletcher.github.io/peg-multimarkdown/> - -#% markdown pandoc v multimarkdown -<https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown> - -#% rST v markdown -<http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext> - -***** 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 -<http://docutils.sourceforge.net/rst.html> -<http://docutils.sourceforge.net/docs/user/rst/quickref.html> -<http://docutils.sourceforge.net/docs/user/rst/quickstart.html> -<http://en.wikipedia.org/wiki/ReStructuredText> -<http://sphinx-doc.org/rest.html> - -<http://stackoverflow.com/questions/2746692/restructuredtext-tool-support> - -#% rST v markdown -<http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext> - -***** 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: <http://www.python.org/> - or - External hyperlinks, like `Python - <http://www.python.org/>`_. - [] 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 -<http://en.wikipedia.org/wiki/Textile_(markup_language)> -v2.4 -<http://www.txstyle.org/> -v2 -<http://redcloth.org/hobix.com/textile/> - -***** 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 - -*** TODO [#C] refactor ruby :ongoing: - -** bugs :bug: - -*** misc, unclassified - -**** 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 - -*** DBT Outstanding bugs -- sisu caught by removal of ruby-dbi - -**** TODO ONGOING #746740 [n|u] manpages incomplete - -Date: Sat, 03 May 2014 08:45:49 +0200 -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -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 <daniel.baumann@progress-technologies.net> -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' - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744352> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -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 <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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 - -**** TODO [#C] #744354 [w|u] sisu output: please do not add '<' and '>' around urls - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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: - - <http://example.org> - -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 - - -**** TODO [#B] #744390 [w|u] sisu: empty sections are ignored - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744390> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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 - -**** TODO [#D] #744395 [w|u] sisu output: half-page title page in landscape output - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744395> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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 - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744396> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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 - -**** TODO [#C] #744407 [w|u] sisu: possibility to influence content/formating of the title page - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744407> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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] #744409 [w|u] sisu output: urls in code blocks are not linkified - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744409> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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 - -**** TODO [#C] #744685 [w|u] sisu output: copy&past-able wrapped code blocks - <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=744685> - -From: Daniel Baumann <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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 <daniel.baumann@progress-technologies.net> -To: Debian Bug Tracking System <submit@bugs.debian.org> -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<br />(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 -* Reference versions -** v5 -5.6.2 -5.6.1 -5.5.6 (5.5.5) |