Extra Detail: Better Indent Features Are Needed

-- 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 
Topic revision: r3 - 02 May 2013, GeorgeClark
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy