--
JohnHenning - 01 May 2013
Easy-to-use indenting
Importance for moderately complex pages
I should like to politely suggest that the lack of easy-to-use
indenting is a substantial impediment for readers of
Foswiki-rendered pages.
Surely the usage model described below is not uncommon;
therefore, easy-to-use solutions would be of great benefit.
Usage model
- Pages cover technical topics
- Many can edit
- One assigned primary maintainer
- Primary maintainer commonly uses the wiki syntax
- Occasionally escapes to HTML
- Does not trust wysiwyg editors
- Native language for readers is, often, not English
- Pages have moderate complexity. Example:
- 9 printed pdf pages
- 8 top-level sections (rendered as <h1>
- 43 total sections
- Deepest level is <h4>
- Example TOC is at very bottom of this topic
Problem
- Readers get lost
- Pages feel jumbled and confused
- The hierarchy of topic/subtopic that is so obvious in the TOC is not obvious in the document itself
- Example: Reader is on page 5 and sees sub-headings for
The problem
Solutions
but commonly does not recall that this goes with the parent section "Panda vs. wolf features" and grand-parent section "Interpretations from minutes"
- Scanning backwards in the page may lead the VERY astute reader to note the above superior-level headings - provided that the skin renders sufficiently differently to make their parental relationships obvious.
Desired solution
Better use of
- white space
- heading font sizes
- borders
Indent headings
- A useful answer: http://foswiki.org/Support/Question1279?raw=on
- Which can easily be extended by adding font size or border selections to the headings
- Still, it would be nice to have the following, to save the user the trouble of writing a <style> section.
- If the optional number is included, it specifies the indentation as number and unit to add per level; otherwise foswiki applies a default of '1em' per level.
%INDENT_HEADERS% or
%INDENT_HEADERS{"indent"}%
example: %INDENT_HEADERS{"13 px"}%
Indent paragraphs and other content
- Desired feature: paragraphs (and other content) match the most recent heading.
- If the most recent heading was indented by 13px, then
- Create a <div style="margin-left:13 px;"> immediately after the title
- end with </div> just before next section title.
- If the optional indent string is included, it specifies the additional indentation that is desired beyond the indentation of the most recent heading. Example:
%INDENT_PARAGRAPHS% or
%INDENT_PARAGRAPHS{"indent"}%
example: %INDENT_PARAGRAPHS{"0.2 em"}%
Alternatives
- Syntax for "indent level is 13px until I tell you different"; or
- Syntax for "indent level is 3em until next heading"; or
- As a last resort: syntax for "indent level is 3px for this paragraph"
What is Available Now?
- There are google hits about indenting in foswiki
- Many lead to http://foswiki.org/Tasks/Item2516
- Is the above page correctly read as:
- Known problem, at least 4 years old
- Some coding done, had side effects
- No solution released as of April 2013
- (hmmm.... the very top says Current State"Waiting for release", but the bottom seems to indicate that some indent feature or another was released in 1.2.... so where would I find it? I have tried multiple variations of the space-space-space-colon-space idea... no luck, nor have these eyes spotted anything while searching documentation.)
This is waiting for release in Release 1.2, which is still a ways away from release. You can test it using http://trunk.foswiki.org/, the same wikiname / password on foswiki.org will work for the trunk site. trunk.foswiki.org runs from a svn checkout. Note: This topic should be moved into the Development web, and set as a feature request. -- GeorgeClark - 02 May 2013
Workaround: tedious, error-prone
Here is the workaround that I am using for now. Please tell me
that there is a better way!
Add style section [angle brackets omitted]
style type="text/css"
!--
/* ... Place your formats here ... */
h1 { padding-left:1px; border-top:thin solid gray;
margin:1em .1em .2em .1em;}
h2 { padding-left:8px; margin:.8em .1em .2em .1em;}
h3 { padding-left:16px; margin:.6em .1em .2em .1em;}
h4 { padding-left:24px; margin:.4em .1em .2em .1em;}
.ind2 { padding-left:16px; }
.ind3 { padding-left:24px; }
.ind4 { padding-left:32px; }
--
/style
And then within the text, add div markers [angle brackets
omitted in this example]
---++++ A level 3 heading
div class="ind3"
some info about the topic
* with bullets
* and more
and maybe another pargraph
/div
---++++ A level 4 heading
div class="ind4"
some info about the topic
* with bullets
* and more
/div
Appendix - example "moderately complex" TOC
Here is the actual table of contents for a page where I am the
primary maintainer, obfuscated by word choice. It is here to
provide a sense for the level of complexity.
Yes, it could be argued that the page might benefit fromb being
broken into multiple pages; but it has not yet reached the point
where it
must be split, in the opinion of the maintainer.
"Moderately complex" TOC
A real example, obfuscated by word substitutions
Mumble Reindeers
Reports
Sword, resword, and alerts
Mumble philosophy
Peer Mumble
Why worry about candle?
When is candle NOT needed?
Characteristics of a nimrod
Communicating mumble comments
If you are not the primary mumbler
Primary mumblers
Ticket from who?
woodget
Non-woodget
How do you know who the woodgets are?
Including castigation from olives
Update agenda
No more quizzes
Interpretations from minutes
Basket Documentation
Finish
Isolation Gear
Meeting Place
Namby-pamby
Panda vs. wolf features
The problem
Solutions
Prince Features
Staggering
Syntax State
Test and twist - must they vanish?
96-except
Mumbler tips - add yours here
Compare Wolf Options
How to do a Refrigerator Sword Mumble
Reaper fees
strip
Vendor reindeer pages
Acme Reindeer Pages
Pending Ideas for Standardization... not in effect
Stumble Audit
Oscar Naming
Wolf version