# 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.
Pastie