# Wrapping in TextMate:

It would be nice if we could get indented soft wrap in TextMate.  To that end I'm making this list of all the different types of wrapping we may want to support, and some explanations of what type of flexibility is needed.

## Markdown:

There are several valid ways to compose various markdown elements such as quoted text and lists, and we want to support them to the extent possible:

### Lists:

    If this is a regular paragraph,

    * This is a list with a really long
      line in it.  we want the line with
      the `*` to have a hanging indent.

    * This is item 2 in the list

      * this is a sublist with a long
        line itself.  it should be
        wrapped as well
      * the sublist's second item
      * in markdown 2 i think we
        want to disallow these
        two-space indents for
        sublists

    * back to the main list

----

    Here is another list:

      * the items are indented
      * like so

        We can put a sublist inside
        this list with ease:

          * and the sub-items
            are also indented
          * like so

        And then go back to the item
        in the main list, in an easy
        readable fashion

      * this makes the whole list
        indented from regular text

    Regular text just stays flush to the left

      * The only downside with such indentation
          * is that sublists seem rather deeply
            indented
          * when there's no regular body text
            in the original list
      * Like in this example

    This is my preferred way of indenting
    nested lists, nonetheless

----

    Numbered lists are harder, because
    there are many ways to write them:

    1. We can write the numbers all the way
    to the left edge and not indent
    2. Like this

----

    1. Writing the numbered list just like
       this (or similar).
    2. If we continue this list, it
       will look okay
    15. But if our numbers grow, suddenly
        so does our indent… not so hot.

    To this end we might want a list like:

     1. here's another list, this time with
        the text starting on a tab stop.
     2. this one makes sure that things
        look good.
    12. and we can even get the numbers
        (up through 99 at least) to be
        right-aligned
    13. though currently a bug in
        Markdown's implementation prevents
        this from working as it should.
        Markdown 2.0 should fix this, and
        it would be slick if TM even
        wrote the lists like this by
        default when typing along.

    Of course, if we're going to indent lists
    and quotes by two spaces, then we could
    also do this with numbered lists:

      1. This list ends up not keeping
        the paragraph exactly aligned
        with the first line
      2. However it avoids the whole
        right-aligned dilemma
      14. And for big numbers
        the list just gets a bit more
        out of alignment.

### Quoted text

For quoted text, things are if anything even worse.

    Here's a paragraph
    > In email, quoted text generally
    > starts with a `>` mark
    >> A sub-quote starts with two
    >> `>` marks instead
    >>> And we can keep increasing
    >>> the quote level as we like

    Now, sometimes people put spaces
    between qoute marks:

    > This is a quoted bit piece
    > of text.
    > > This is a sub-quote
    > > > etc. etc.
    > And back to the first quote

    But in markdown, we can also indent
    before a quote mark, so that the
    quoted text is indented as it
    would be when the document is
    typeset:

      > so this text is quoted, and
      > we can see visually that
      > it's indented from surrounding
      > text
      >
      >   > we can make doubly quoted
      >   > text indented even more
      >   > using 4 spaces between.
      >   >
      >   >   > If these are typeset
      >   >   > with little quote bars
      >   >   > down the left, they
      >   >   > now bear a strong
      >   >   > resemblance now to their
      >   >   > final form.
      >
      > And it's easy to get back to an
      > earlier quotation level.
      >
      >   * For reference, here's a list
      >     inside some quoted text.
      >   * With two items in it
      >
      > And back to the original quotation
      >
      >   >   >   >   >   > One big
      >   >   >   >   >   > downside with
      >   >   >   >   >   > this method
      >   >   >   >   >   > is it doesn't
      >   >   >   >   >   > work well with
      >   >   >   >   >   > deeply nested
      >   >   >   >   >   > quotations.

Unfortunately, this style takes up lots of extra space (especially with deep nesting, as in emails), even if it's more readable.

*Aside:* For the purposes of Markdown 2.0, I'm not sure how this should be done.  I suppose it can have a rule something like, if there are 4 spaces after the last `>`, then we get pre-formatted text, or similar.  I don't think it's as big a problem with lists (to require 4 spaces or a tab for each additional level) as it is with quotes, because lists aren't commonly nested very deeply, whereas with email quotations, nesting can be very deep indeed.

----

We want textmate to do hanging indents on these, and possibly even do nifty stuff like putting in "ghost" `>` characters for us.  So the wrapping might look like:

    This is a paragraph

    > And this is a quote with a long
      line in it, which wraps.

Or might look like this:

    This is a paragraph

      > This is a quote with a long line
      > but a ghost `>` character keeps it
      > looking like it's hard wrapped.

### Pre-formatted text:

We probably don't want some lines to wrap at all.  In the case of markdown, this includes lines of Pre-formatted text, such as:

    The following code block should not wrap at all:

        def spam(eggs, ham): return (lambda x, y: (eggs*x + ham*y)**(1/2) - 1)

    Whew, that was a long line

This will allow for the exact quoting of code, without getting weird wrapping effects.

### Long urls in references:

We don't want long urls in reference style links to wrap, in Markdown. For instance, in my key binding article, I have the following at the bottom:

    [appledev-plist]: http://developer.apple.com/documentation/Cocoa/Conceptual/PropertyLists/PropertyLists.html#//apple_ref/doc/uid/10000048
    [appledev-keybindings]: http://developer.apple.com/documentation/Cocoa/Conceptual/InputManager/Concepts/KeyBindings.html#//apple_ref/doc/uid/20001037-DontLinkElementID_2050128a
    [appledev-text-system-defaults]: http://developer.apple.com/documentation/Cocoa/Conceptual/BasicEventHandling/Tasks/TextDefaultsAndBindings.html
    [appledev-nsres]: http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSResponder.html
    [appledev-nstext]: http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSText.html
    [appledev-text-input]: http://developer.apple.com/documentation/Cocoa/Conceptual/InputManager/index.html
    [apple-ucode]: http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/CORPCHAR.TXT

It's annoying for this to wrap.

## HTML

In html, xml (like svg), etc. it would be slick if soft wrap really worked well.

### Within opening/closing

For instance, in the following svg version of the UK flag, some lines are way too long.  It would be nice if these wrapped, in an "intelligent" fashion: not wrapping some scopes at all, and wrapping others at logical places.

    <?xml version="1.0" standalone="yes"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
    <svg id="Flag of the United Kingdom" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="1200" height="600" viewBox="0 0 1200 600">
      <defs>
        <g id="diagonal">
          <rect fill="white" width="68" height="6" y="-3" />
          <rect fill="#CF142B" width="34" height="2" />
          <rect fill="#CF142B" width="34" height="2" x="34" y="-2" />
        </g>
      </defs>
      <g id="Flag of the United Kingdom" transform="scale(20,20)">
        <rect id="blue background" fill="#00247D" width="60" height="30" />
        <g id="saltires">
          <use id="NW-SE" xlink:href="#diagonal" transform="rotate(26.56505117707799001891544321551918983459472656)" />
          <use id="NE-SW" xlink:href="#diagonal" transform="translate(0,30) rotate(-26.56505117707799001891544321551918983459472656)" />
        </g>
        <g id="white cross" fill="white">
          <rect width="10" height="30" x="25" />
          <rect width="60" height="10" y="10" />
        </g>
        <g id="red cross" fill="#CF142B">
          <rect width="6"  height="30" x="27" />
          <rect width="60" height="6"  y="12" />
        </g>
      </g>
    </svg>

In this case, we probably want the doctype to wrap, as well as the `svg` tag, and the `use` tags.  An ideal wrapping is probably something like:

     1  <?xml version="1.0" standalone="yes"?>
     2  <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
     •    "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
     3  <svg id="Flag of the United Kingdom" version="1.1"
     •      xmlns="http://www.w3.org/2000/svg"
     •      xmlns:xlink="http://www.w3.org/1999/xlink"
     •      width="1200" height="600" viewBox="0 0 1200 600">
     4    <defs>
     5      <g id="diagonal">
     6        <rect fill="white" width="68" height="6" y="-3" />
     7        <rect fill="#CF142B" width="34" height="2" />
     8        <rect fill="#CF142B" width="34" height="2" x="34" y="-2" />
     9      </g>
    10    </defs>
    11    <g id="Flag of the United Kingdom" transform="scale(20,20)">
    12      <rect id="blue background" fill="#00247D" width="60"
     •          height="30" />
    13      <g id="saltires">
    14        <use id="NW-SE" xlink:href="#diagonal"
     •            transform="rotate(26.56505117707799001891544321551918983459472656)" />
    15        <use id="NE-SW" xlink:href="#diagonal"
     •            transform="translate(0,30) rotate(-26.56505117707799001891544321551918983459472656)" />
    16      </g>
    17      <g id="white cross" fill="white">
    18        <rect width="10" height="30" x="25" />
    19        <rect width="60" height="10" y="10" />
    20      </g>
    21      <g id="red cross" fill="#CF142B">
    22        <rect width="6"  height="30" x="27" />
    23        <rect width="60" height="6"  y="12" />
    24      </g>
    25    </g>
    26  </svg>

Where for instance we don't get wrapping in the middle of an attribute (like halfway through one of those very long numbers, for instance)

### Inside tags

In html, or xml plists, &c., the tags themselves aren't generally so absurdly long, but their content might be.  There are a couple of ways that the actual file could be stored, listed below:

    <ul>
      <li>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</li>
      <li>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</li>
    </ul>

----

    <ul>
      <li>
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
      </li>
      <li>
        Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
      </li>
    </ul>

The second of these is quite straight-forward.  We simply want to wrap to the exact level to which the beginning of the line is wrapped, like so:

    <ul>
      <li>
        Lorem ipsum dolor sit amet, consectetur
        adipisicing elit, sed do eiusmod tempor
        incididunt ut labore et dolore magna aliqua.
        Ut enim ad minim veniam, quis nostrud
        exercitation ullamco laboris nisi ut aliquip
        ex ea commodo consequat.
      </li>
      <li>
        Duis aute irure dolor in reprehenderit in
        voluptate velit esse cillum dolore eu fugiat
        nulla pariatur. Excepteur sint occaecat
        cupidatat non proident, sunt in culpa qui
        officia deserunt mollit anim id est laborum.
      </li>
    </ul>

It is the first scenario which offers a couple of solutions.  The simplest is to simply wrap every line after the first to the same indentation level.  This is the approach which BBEdit adopts in their most recent version:

    <ul>
      <li>Lorem ipsum dolor sit amet, consectetur
      adipisicing elit, sed do eiusmod tempor
      incididunt ut labore et dolore magna aliqua.
      Ut enim ad minim veniam, quis nostrud
      exercitation ullamco laboris nisi ut aliquip
      ex ea commodo consequat.</li>
      <li>Duis aute irure dolor in reprehenderit in
      voluptate velit esse cillum dolore eu fugiat
      nulla pariatur. Excepteur sint occaecat
      cupidatat non proident, sunt in culpa qui
      officia deserunt mollit anim id est
      laborum.</li>
    </ul>

This doesn't seem satisfactory.  A separate method would be to allow scope and/or a regular expression on the line to set the number of tab stops to indent.  We may want the text in this case to be wrapped to one (or maybe two) tab stops beyond the original:

    <ul>
      <li>Lorem ipsum dolor sit amet, consectetur
        adipisicing elit, sed do eiusmod tempor
        incididunt ut labore et dolore magna aliqua.
        Ut enim ad minim veniam, quis nostrud
        exercitation ullamco laboris nisi ut aliquip
        ex ea commodo consequat.</li>
      <li>Duis aute irure dolor in reprehenderit in
        voluptate velit esse cillum dolore eu fugiat
        nulla pariatur. Excepteur sint occaecat
        cupidatat non proident, sunt in culpa qui
        officia deserunt mollit anim id est
        laborum.</li>
    </ul>

A more complicated method would allow the text to be indented so that it aligns with the end of the opening tag:

    <ul>
      <li>Lorem ipsum dolor sit amet, consectetur
          adipisicing elit, sed do eiusmod tempor
          incididunt ut labore et dolore magna
          aliqua. Ut enim ad minim veniam, quis
          nostrud exercitation ullamco laboris nisi
          ut aliquip ex ea commodo consequat.</li>
      <li>Duis aute irure dolor in reprehenderit
          in voluptate velit esse cillum dolore eu
          fugiat nulla pariatur. Excepteur sint
          occaecat cupidatat non proident, sunt in
          culpa qui officia deserunt mollit anim
          id est laborum.</li>
    </ul>

Or perhaps even with the first character of the tag content--something like:


    <ul>
      <li> Lorem ipsum dolor sit amet, consectetur
           adipisicing elit, sed do eiusmod tempor
           incididunt ut labore et dolore magna
           aliqua. Ut enim ad minim veniam, quis
           nostrud exercitation ullamco laboris nisi
           ut aliquip ex ea commodo consequat.</li>
      <li> Duis aute irure dolor in reprehenderit
           in voluptate velit esse cillum dolore eu
           fugiat nulla pariatur. Excepteur sint
           occaecat cupidatat non proident, sunt in
           culpa qui officia deserunt mollit anim
           id est laborum.</li>
    </ul>

The problem that I can envision with a scheme like this is that it could get rather ugly if the tags have lots of attributes:


    <ul>
      <li id="foobaria" class="wow"> Lorem ipsum
                                     dolor sit amet,
                                     consectetur
                                     adipisicing elit,
                                     sed do eiusmod
                                     tempor incididunt
                                     ut labore et
                                     dolore magna
                                     aliqua. Ut enim
                                     ad minim veniam,
                                     quis nostrud
                                     exercitation
                                     ullamco laboris
                                     nisi ut aliquip
                                     ex ea commodo
                                     consequat.</li>
      <li id="baz"> Duis aute irure dolor in
                    reprehenderit in voluptate velit
                    esse cillum dolore eu fugiat nulla
                    pariatur. Excepteur sint occaecat
                    cupidatat non proident, sunt in
                    culpa qui officia deserunt mollit
                    anim id est laborum.</li>
    </ul>

Which is, quite frankly, ridiculous.  So maybe people would in this type of scheme need the ability to set a maximum level to which the wrap would happen (of course this maximum would need to be settable on a case-by-case basis).

But the problem is not only with really exended lines.  It's also annoying that in the above, the two paragraphs don't line up.  I much prefer the one tab method in this case:

    <ul>
      <li id="foobaria" class="wow"> Lorem ipsum dolor
        sit amet, consectetur adipisicing elit, sed do
        eiusmod tempor incididunt ut labore et dolore
        magna aliqua. Ut enim ad minim veniam, quis
        nostrud exercitation ullamco laboris nisi ut
        aliquip ex ea commodo consequat.</li>
      <li id="baz"> Duis aute irure dolor in
        reprehenderit in voluptate velit esse cillum
        dolore eu fugiat nulla pariatur. Excepteur sint
        occaecat cupidatat non proident, sunt in culpa
        qui officia deserunt mollit anim id est
        laborum.</li>
    </ul>

The above is pretty readable, IMO, especially with some proper syntax highlighting to separate content from tags.

----

With a customizable enough system, we could maybe even make the code look like it was hard wrapped.  It could wrap something like:

     1  <ul>
     2    <li id="foobaria" class="wow">
     •      Lorem ipsum dolor sit amet, consectetur
     •      adipisicing elit, sed do eiusmod tempor
     •      incididunt ut labore et dolore magna
     •      aliqua. Ut enim ad minim veniam, quis
     •      nostrud exercitation ullamco laboris
     •      nisi ut aliquip ex ea commodo consequat.
     •    </li>
     3    <li id="baz">
     •      Duis aute irure dolor in reprehenderit
     •      in voluptate velit esse cillum dolore
     •      eu fugiat nulla pariatur. Excepteur
     •      sint occaecat cupidatat non proident,
     •      sunt in culpa qui officia deserunt
     •      mollit anim id est laborum.
     •    </li>
     4  </ul>

The above would be pretty neat, but might get users confused about whether their text was hard or soft wrapped, and it might be disconcerting to be typing along on a line, and with the addition of one letter, have the whole thing get reformatted drastically:

    1  <ul>
    2    <li class="wow"> Lorem ipsum dolor s|</li>
    3  </ul>

becoming

    1  <ul>
    2    <li class="wow">
    •       Lorem ipsum dolor sit|
    •    </li>
    3  </ul>

where `|` represents the insertion point.  This might also be a potential performance drag.  The following would be more in line with (especially unfamiliar) user expectations:

    1  <ul>
    2    <li class="wow"> Lorem ipsum dolor
    •      sit|</li>
    3  </ul>


----

Of course, this whole thing somewhat comes down to personal preference, which maybe is an argument for flexibility (however, most new users won't be able to figure out a very complicated scheme for setting these indentation levels, so KISS is also an important principle here).

## Source code

In source code, I have no idea how various things should be indented.  In general, I just hard wrap everything, as python is pretty amenable to 80 character line limits when coding, and I don't write much code in extremely verbose languages like Objective C.  The only place where I can really see myself liking any kind of soft wrap in code is inside comments and strings.


## Option: Let's Go More Basic

Having Textmate deduce what sort of wrapping to do contextual is good, but sometimes it's nice to have some simpler options.  Consequently, I'd suggest the following, at minimum, to just be Preferences/View Menu options:

(Taken from http://ticket.macromates.com/show?ticket_id=4EFB31A8)
1. No-Indent Wrap: Where soft-wrapped subsequent lines start at column 0.
2. Same Indent Wrap: Where soft-wrapped subsequent lines start at the same indent as the original line.
3. Plus-One Indent Wrap: Where soft-wrapped subsequent lines start at the same indent as the original line plus one additional indent.