cross
New Foswiki release 2.1.6 is available with important security fixes.
Sourceforge foswiki email lists being discontinued. Subscribe to the new Foswiki announce and discuss lists at MailingLists

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 - This page was cached on 22 Jun 2018 - 21:42.

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