TiddlyWiki5/plugins/tiddlywiki/text-slicer/docs.tid

title: $:/plugins/tiddlywiki/text-slicer/docs

! Introduction

This plugin contains tools to help work with documents that are structured as a hierarchical outline of tiddlers.  The structural relationships within the document are expressed as lists: for example, headings have a list specifying the content to be shown under the heading.

TiddlyWiki is built on the philosophy that text is easier to re-use and work with if it is sliced up into separate chunks that can be independently manipulated, and then woven back together to make up stories and narratives for publication.

The components within the text slicer plugin include:

* ''the slicer'', a tool that slices up an existing monolithic document according to the headings, lists and paragraphs. It is available as a toolbar button for the browser, or as a command for use under Node.js
* ''document preview column'', a new sidebar on the left that shows the full text of any documents in the wiki and allows individual tiddlers to be opened with a click
* ''exporters'' for exporting the individual documents as HTML files (and for previewing them)

! Slicing Monolithic Documents

The tool can slice any tiddler that can be rendered as HTML, including both WikiText and HTML itself.

Documents created with Microsoft Word will need to be first converted to HTML. The library [[mammoth.js|https://github.com/mwilliamson/mammoth.js]] is recommended for this purpose.

!! Browser

In the browser, you can slice a monolithic document tiddler using the slicer toolbar button.

!! Node.js

The `--slice` command allows a tiddler to be sliced under Node.js:

```
tiddlywiki mywiki --slice SourceDocument --build index
```

! Working with the Document Preview Column

The document preview column appears at the left side of the screen. The content of headings can be collapsed and expanded to help navigation. Clicking on a tiddler opens the corresponding tiddler in the main story river.

Clicking ''Show toolbar'' causes each tiddler be preceded by a toolbar showing the underlying title. It can be edited directly to rename the tiddler. References to the tiddler in the ''tags'' and ''list'' are automatically updated to reflect the change, but note that links to the tiddler will not be automatically changed.

The following theme tweaks should be applied to enable the preview column:

* Set [[story left position|$:/themes/tiddlywiki/vanilla/metrics/storyleft]] to ''400px'' (or more)
* It is recommended to also set the [[sidebar layout|$:/themes/tiddlywiki/vanilla/options/sidebarlayout]] to ''fluid-fixed''.

! Exporting Documents

Documents can be saved under Node.js, or previewed in the browser.

!! Exporting Documents in the Browser

To preview a document, locate it in the preview column and click the button labelled "View document". The document will open in plain text in a new window. The window will be automatically updated as you work on the document.

!! Exporting Documents under Node.js

[TBD]

! Sliced Document Format

!! Introduction

Individual tiddlers are created for each heading, paragraph and list item. They are linked together into a hierarchical outline using lists.

For example, consider a tiddler titled ''Example'' containing this simple text:

<<<
! This is a heading

This is a paragraph.

* And the first list item
* Second list item
<<<

It will be sliced up into:

* a tiddler for the overall document
** a tiddler for the heading
*** a tiddler for the paragraph
*** a tiddler for the list
**** and a tiddler for each list item

These tiddlers are bound together using lists: the parent tiddler has a ''list'' field that lists each child in the correct order.

!! Slicing Process

Slicing generates the following component tiddlers.

Tiddler titles are generated automatically in most cases (but can subsequently be changed manually). The automatically generated title is made up of concatenating the following elements:

* root text (e.g. ''para'')
* a dash ''-''
* the first few words of the text of the item (up to 40 characters), separated with dashes ''-''
* if necessary, a dash ''-'' and a numerical index to make the title unique

For example, ''para-how-to-use-pentagonal-tiles 23''.

Any CSS classes used in the original document are assigned as tags to the associated tiddlers.

!!! Document

The document itself is represented by a tiddler with the following fields:

* ''toc-type'': the text "document"
* ''title'': the text ''"Sliced up "'' plus the title of the tiddler that was sliced
* ''text'': Available for comments about the document
* ''list'': ordered list of tiddlers making up the root level of this document

!!! Headings

Tiddlers representing headings have the following fields:

* ''toc-type'': the text "heading"
* ''toc-heading-level'': the heading level "h1", "h2", "h3" etc.
* ''title'': an automatically generated unique title
* ''text'': the text of the heading
* ''list'': ordered list of tiddlers tagged with this heading (i.e. the child headings, paragraphs and lists displayed under this heading)
** In addition, any CSS classes found in the HTML are converted into tags

!!! Paragraphs

Tiddlers representing paragraphs have the following fields:

* ''toc-type'': the text "paragraph"
* ''title'': an automatically generated unique title
* ''text'': the text of the paragraph
* ''tags'': any CSS classes found in the HTML are converted into tags

!!! Lists

Lists are represented by several tiddlers: one for the list itself, and one for each item in the list.

The tiddler representing the list itself has the following fields:

* ''toc-type'': the text "list"
* ''toc-list-type'': the text "ul" or "ol"
* ''toc-list-filter'': the default filter used to generate the titles of the list items
* ''title'': an automatically generated unique title
* ''list'': ordered list of titles of tiddlers representing the items in this list
* ''tags'': any CSS classes found in the HTML are converted into tags

The tiddlers representing items within the list have the following fields:

* ''toc-type'': the text "item"
* ''title'': an automatically generated unique title
* ''text'': the text of the list item
* ''tags'': any CSS classes found in the HTML are converted into tags

!!! Definition lists

Definition lists are represented by several tiddlers: one for the definition list itself, and one for each term and definition in the list.

The tiddler representing the definition list itself has the following fields:

* ''toc-type'': the text "def-list"
* ''toc-list-filter'': the default filter used to generate the titles of the definition list items
* ''title'': an automatically generated unique title
* ''list'': ordered list of titles of tiddlers representing the items (terms and/or definition) in the definition list
* ''tags'': any CSS classes found in the HTML are converted into tags

The tiddlers representing terms within the definition list have the following fields:

* ''toc-type'': the text "term"
* ''title'': an automatically generated unique title
* ''text'': the text of the definition list term
* ''tags'': any CSS classes found in the HTML are converted into tags

The tiddlers representing definitions within the definition list have the following fields:

* ''toc-type'': the text "definition"
* ''title'': an automatically generated unique title
* ''text'' : the text of the definition list definition
* ''tags'': any CSS classes found in the HTML are converted into tags

!!! Images

Tiddlers representing images have the following fields:

* ''toc-type'': the text "image"
* ''title'': an automatically generated unique title
* ''type'': appropriate content type for the image (eg "image/jpeg")

!!! Notes

Notes are available during editing but hidden for static renderings. The slicing mechanism does not generate notes; they can only be subsequently added manually. Tiddlers representing notes have the following fields:

* ''toc-type'': the text "note"
* ''title'': an automatically generated unique title
* ''text'': the text of the note
* ''tags'': any CSS classes found in the HTML are converted into tags

! Document Metadata, Tags and Classes

[TBD]