diff --git a/doc/Tabular.txt b/doc/Tabular.txt new file mode 100644 index 0000000..43b1bf6 --- /dev/null +++ b/doc/Tabular.txt @@ -0,0 +1,151 @@ + +*Tabular.txt* Configurable, flexible, intuitive text aligning + + *tabular* *tabular.vim* + + #|#|#|#|#| #| #| ~ + #| #|#|#| #|#|#| #| #| #| #|#|#| #| #|#| ~ + #| #| #| #| #| #| #| #| #| #| #|#| ~ + #| #| #| #| #| #| #| #| #| #| #| ~ + #| #|#|#| #|#|#| #|#|#| #| #|#|#| #| ~ + + For Vim version 7.0 or newer + + By Matt Wozniski + mjw@drexel.edu + + Reference Manual ~ + + *tabular-toc* + +1. Description |tabular-intro| +2. Walkthrough |tabular-walkthrough| + +The functionality mentioned here is a plugin, see |add-plugin|. +You can avoid loading this plugin by setting the "Tabular_loaded" global +variable in your |vimrc| file: > + :let g:tabular_loaded = 1 + +============================================================================== +1. Description *tabular-intro* + +Sometimes, it's useful to line up text. Naturally, it's nicer to have the +computer do this for you, since aligning things by hand quickly becomes +unpleasant. While there are other plugins for aligning text, the ones I've +tried are either impossibly difficult to understand and use, or too simplistic +to handle complicated tasks. This plugin aims to make the easy things easy +and the hard things possible, without providing an unnecessarily obtuse +interface. It's still a work in progress, and criticisms are welcome. + +============================================================================== +2. Walkthrough *tabular-walkthrough* + +Tabular's commands are based largely on regular expressions. The basic +technique used by Tabular is taking some regex that matches delimiters, +splitting the input lines at those delimiters, padding the non-delimiter parts +of the lines with spaces, and joining things back together again. + +For instance, consider starting with the following lines: +> + Some short phrase,some other phrase + A much longer phrase here,and another long phrase +< +Let's say we want to line these lines up at the commas. We can tell +Tabularize to do this by passing a pattern matching , to the Tabularize +command: +> + :Tabularize /, + + Some short phrase , some other phrase + A much longer phrase here , and another long phrase +< +So, now the commas line up. Splitting the lines on commas, Tabular realized +that 'Some short phrase' would need to be padded with spaces to match the +length of 'A much longer phrase here', and it did that before joining the +lines back together. You'll also notice that, in addition to the spaces +inserting for padding, extra spaces were inserted between fields. That's +because by default, Tabular prints things left-aligned with one space between +fields. If you wanted to print things right-aligned with no spaces between +fields, you would provide a different format to the Tabularize command: +> + :Tabularize /,/r0 + + Some short phrase, some other phrase + A much longer phrase here,and another long phrase +< +A format specifier is either l, r, or c, followed by one or more digits. If +the letter is l, the field will be left aligned, similarly for r and right +aligning and c and center aligning. The number following the letter is the +number of spaces padding to insert before the start of the next field. +Multiple format specifiers can be added to the same command - each field will +be printed with the next format specifier in the list; when they all have been +used the first will be used again, and so on. So, the last command right +aligned every field, then inserted 0 spaces of padding before the next field. +What if we wanted to right align the text before the comma, and left align the +space after the comma? The command would look like this: +> + :Tabularize /,/r1c1l0 + + Some short phrase , some other phrase + A much longer phrase here , and another long phrase +< + +That command would be read as "Align the following text, splitting fields on +commas. Print everything before the first comma right aligned, then 1 space, +then the comma center aligned, then 1 space, then everything after the comma +left aligned." Notice that the alignment of the field the comma is in is +irrelevant - since it's only 1 cell wide, it looks the same whether it's right, +left, or center aligned. Also notice that the 0 padding spaces specified for +the 3rd field are unused - but they would be used if there were enough fields +to require looping through the fields again. For instance: +> + abc,def,ghi + a,b + a,b,c + + :Tabularize /,/r1c1l0 + + abc , def, ghi + a , b + a , b , c +< +Notice that now, the format pattern has been reused; field 4 (the second comma) +is right aligned, field 5 is center aligned. No spaces were inserted between +the 3rd field (containing "def") and the 4th field (the second comma) because +the format specified 'l0'. + +But, what if you only wanted to act on the first comma on the line, rather than +all of the commas on the line? Let's say we want everything before the first +comma right aligned, then the comma, then everything after the comma left +aligned: +> + abc,def,ghi + a,b + a,b,c + + :Tabularize /^[^,]*\zs,/r0c0l0 + + abc,def,ghi + a,b + a,b,c +< +Here, we used a vim regex that would only match the first comma on the line. +It matches the beginning of the line, followed by all the non-comma characters +up to the first comma, and then forgets about what it matched so far and +pretends that the match starts exactly at the comma. + +But, now that this command does exactly what we want it to, it's become pretty +unwieldly. It would be unpleasant to need to type that more than once or +twice. The solution is to assign a name to it. +> + :AddTabularPattern my_commas /^[^,]*\zs,/r0c0l0 +< +Now, typing ":Tabularize my_commas" will do the same thing as typing the whole +pattern out each time. Of course this is more useful if you store the name in +a file to be used later. + +NOTE: Documentation on how to do that will follow; it needs to go in an + after/plugin/ dir to be loaded after Tabular.vim + +============================================================================== +vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: