1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/README.l3text	Mon Nov 28 13:15:16 2011 +0200
     1.3 @@ -0,0 +1,380 @@
     1.4 +
     1.5 +
     1.6 +l3text (или l3) это программа, которая предоставляет интерфейс 
     1.7 +к информации, записанной LiLaLo, прямо в командной строке.
     1.8 +
     1.9 +Результаты распознавания записываются с помощью l3-agent
    1.10 +в базу данных SQLite, и они становятся сразу же доступными для
    1.11 +использования с помощью l3text.
    1.12 +
    1.13 +l3text — это набор инструментов, для работы с транскриптами сеансов,
    1.14 +сгруппированные под одной крышей.
    1.15 +
    1.16 +Некоторые примеры использования.
    1.17 +
    1.18 +Показать весь журнал команд в текущем контексте
    1.19 +(начиная с текущего положения).
    1.20 +    $ l3text cat 
    1.21 +
    1.22 +Показать только командные строки или только вывод:
    1.23 +    $ l3text cat -c
    1.24 +    $ l3text cat -o
    1.25 +
    1.26 +Показать последние 10 команд:
    1.27 +    $ l3text tail
    1.28 +
    1.29 +Показать последние 20 команд:
    1.30 +    $ l3text tail -20
    1.31 +
    1.32 +Следить за текущим сеансом, то есть показывать все команды,
    1.33 +выполняющиеся в текущем контексте:
    1.34 +    $ l3text tail -f
    1.35 +
    1.36 +По умолчанию показываются только команды и результаты их выполнения.
    1.37 +Вывод можно настроить:
    1.38 +    $ l3 cat -o time,cline,output
    1.39 +
    1.40 +== Контекст ==
    1.41 +
    1.42 +Все команды, которые вы набираете, и результаты их выполнения
    1.43 +не повисают в воздухе, а дописываются в конец листов,
    1.44 +находящихся в определённых местах.
    1.45 +
    1.46 +Лист, на который попадают команды называется ''контекстом записи''.
    1.47 +
    1.48 +Вы можете набирать команды в разных окнах,
    1.49 +но если они находятся в одном контексте, то они запишутся
    1.50 +на один лист, одна под другой.
    1.51 +
    1.52 +С другой стороны, в одном окне вы можете поменять контекст несколько раз,
    1.53 +и команды, набиравшиеся в этих контекстах, попадут на разные листы.
    1.54 +
    1.55 +По умолчанию контекст равен /default , 
    1.56 +но для удобства дальнейшей работы с записями рекомендуется
    1.57 +задавать нужный контекст, которому соответствуют выполняемые действия.
    1.58 +
    1.59 +Сменить текущий контекст записи можно так:
    1.60 +    l3 context /path/to/new/context
    1.61 +
    1.62 +Просмотреть контекст записи можно так:
    1.63 +    l3 context
    1.64 +
    1.65 +Итак, контекст записи (контекст агента) определяет,
    1.66 +куда попадают команды при записи.
    1.67 +
    1.68 +Мы записывали команды не просто так.
    1.69 +Мы хотим поработать с тем, что мы записали.
    1.70 +Лист, на котором записаны команды, с которыми мы хотим
    1.71 +поработать, определяется ''контекстом чтения''.
    1.72 +
    1.73 +То есть он определяет, какие именно команды
    1.74 +из записанных ранее мы имеем в виду.
    1.75 +
    1.76 +По умолчанию текущий контекст чтения становится равным
    1.77 +текущему контексту записи.
    1.78 +
    1.79 +Смена текущего контекста чтения:
    1.80 +    $ l3 cd /path/to/new/context
    1.81 +или
    1.82 +    $ l3 go /path/to/new/context
    1.83 +
    1.84 +Просмотр доступных контекстов:
    1.85 +    $ l3 ls 
    1.86 +
    1.87 +Просмотреть имя текущего контекста чтения:
    1.88 +    $ l3 pwd
    1.89 +
    1.90 +Символы : и / являются в имени контекста специальными.
    1.91 +
    1.92 +Символ / формирует иерархию контекстов,
    1.93 +а символ : указывает координаты строки в контексте.
    1.94 +
    1.95 +Перейти на 3 команды назад:
    1.96 +    $ l3 go :-3
    1.97 +
    1.98 +Перейти в контекст /adm/lab1, в его самый конец (и находиться
    1.99 +всё время в конце, если он растёт, то есть делаются новые записи):
   1.100 +    $ l3 go /adm/lab1
   1.101 +
   1.102 +Перейти в контекст /adm/lab1, на первую команду grep:
   1.103 +    $ l3 go /adm/lab1:/grep/
   1.104 +
   1.105 +О том, как указывать координаты интересующих нас строк,
   1.106 +написано ниже, в разделе «Интервалы».
   1.107 +
   1.108 +
   1.109 +== Команда ==
   1.110 +
   1.111 +    l3 [ОПЦИИ1] [ИНТЕРВАЛ] [filter ВЫРАЖЕНИЕ] [grep РЕГВЫР] [КОМАНДА] [ОПЦИИ2]
   1.112 +
   1.113 +== Интервалы ==
   1.114 +
   1.115 +По умолчанию операция выполняется над всеми командами,
   1.116 +находящимися в текущем контексте, начиная с текущей точки и до его конца.
   1.117 +
   1.118 +Можно ограничить команды с помощью интервала:
   1.119 +
   1.120 +    выражение
   1.121 +    выражение,выражение
   1.122 +
   1.123 +Примеры:
   1.124 +
   1.125 +    -10,.   последние 10 команд
   1.126 +    .,+3    от текущей команды три вниз
   1.127 +    /grep/  последняя команда grep
   1.128 +    o/grep/ последняя команда, содержащая grep в выводе (output)
   1.129 +    .       текущая строка
   1.130 +    @12:23  команда, выполненная в 12:23 (12:23 текущего часа)
   1.131 +    @08:12:00 команда, выполненная в 8:12:00 (или ближайшая после этого времени)
   1.132 +    1       первая команда в контексте
   1.133 +    $       последняя команда в контексте
   1.134 +    %       весь контекст
   1.135 +
   1.136 +
   1.137 +Интервал указывается перед командой, работу которой он ограничивает:
   1.138 +
   1.139 +    l3 -10,. cat 
   1.140 +напечатать последние 10 команд
   1.141 +
   1.142 +равносильно этому:
   1.143 +    l3 tail -10
   1.144 +
   1.145 +интервал = строка
   1.146 +интервал = строка,строка
   1.147 +интервал = %
   1.148 +строка   = число
   1.149 +         = -число
   1.150 +         = +число
   1.151 +         = @время
   1.152 +         = /регвыр/
   1.153 +         = .
   1.154 +         = $
   1.155 +
   1.156 +== Фильтрация ==
   1.157 +
   1.158 +Можно указать дополнительный фильтр,
   1.159 +который оставляет команды, которые нас интересуют.
   1.160 +
   1.161 +Есть два вида фильтров:
   1.162 +    * по регулярным выражениям
   1.163 +    * по вычисляемому выражению (синтаксис perl с некоторыми отличиями)
   1.164 +
   1.165 +grep -v regexp       инверсия
   1.166 +grep    regexp       прямой поиск
   1.167 +
   1.168 +-f полный
   1.169 +-o только в выводе
   1.170 +-c только в команде (по умолчанию)
   1.171 +
   1.172 +filter выражение
   1.173 +
   1.174 +== Команды ==
   1.175 +
   1.176 +cat
   1.177 +tail
   1.178 +head
   1.179 +history
   1.180 +
   1.181 +Все эти команды являются сокращением для одной команды.
   1.182 +
   1.183 +== Зачем всё это нужно ==
   1.184 +
   1.185 +* использование данных вывода команд при автоматическом продолжении команд
   1.186 +* быстрое выделение и копирование команд
   1.187 +* поиск команд
   1.188 +* привязка ко времени
   1.189 +* подключение к журналу
   1.190 +
   1.191 +=== Tab-completion: Данные вывода команд при наборе других команд ===
   1.192 +
   1.193 +Вы выполнили одну команду, 
   1.194 +и хотите использовать результаты её исполнения
   1.195 +в качестве аргумента другой.
   1.196 +
   1.197 +Например, вы просканировали wifi-сети:
   1.198 +    # iwlist scanning
   1.199 +В выводе команды присутствовали названия SSID, один из которых мы будем использовать дальше.
   1.200 +Было бы классно, если бы дальше, когда мы вводим команду
   1.201 +    # iwconfig wlan0 essid ____
   1.202 +мы могли использовать табуляцию при наборе essid.
   1.203 +
   1.204 +В качестве списка возможных продолжений
   1.205 +должны использоваться сети, которые выдала предыдущая команда.
   1.206 +
   1.207 +Это становится возможным с использованием l3text
   1.208 +(при написании соответствующих расширения для bash_completion).
   1.209 +
   1.210 +=== Быстрое выделение и копирование команд ===
   1.211 +
   1.212 +Ваш друг помогает вам настроить систему по джабберу.
   1.213 +Он присылает вам команды, которые вы творчески перерабатываете
   1.214 +и вводите в консоль.
   1.215 +
   1.216 +Потом, для того чтобы он видел, что получается, вы копируете результаты
   1.217 +исполнения ему в джаббер.
   1.218 +
   1.219 +Например, вы хотите показать результат пяти последних команд:
   1.220 +
   1.221 +В самом простейшем случае (если вы используете графический-джаббер клиент)
   1.222 +    l3 tail -5 | xsel
   1.223 +
   1.224 +Потом идёте в джаббер-клиент и делаете:
   1.225 +    shift-insert
   1.226 +
   1.227 +Можно отправить ему код прямо из консоли:
   1.228 +    l3 tail -5 | sendxmpp igor@chub.in
   1.229 +
   1.230 +Или даже ещё проще, всё, что вы делаете будет копироваться ему:
   1.231 +    l3 tail -f | sendxmpp igor@chub.in
   1.232 +
   1.233 +Или, если вы не хотите, чтобы копировались команды, набранные неверно:
   1.234 +    l3 filter err!=128 tail -f | sendxmpp igor@chub.in
   1.235 +
   1.236 +
   1.237 +Команды l3 не обязательно вызывать в той сессии, где идёт настройка.
   1.238 +Вы можете их вызывать в соседнем терминале, где вообще не идёт запись.
   1.239 +Конечно, вы должны будете указать соответствующий контекст.
   1.240 +
   1.241 +    l3 cd /adm/lab1
   1.242 +
   1.243 +(предполагается, что настройка идёт в /adm/lab1 )
   1.244 +
   1.245 +=== Поиск команд ===
   1.246 +
   1.247 +Вы выполняете настройку сервера,
   1.248 +в ходе которой сделали много инсталляций пакетов.
   1.249 +
   1.250 +Вы делали их в разных окнах, уже сами не помните в каких,
   1.251 +но запись всё время шла.
   1.252 +
   1.253 +Вы хотите увидеть имена пакетов, которые были установлены.
   1.254 +
   1.255 +Простейший вариант:
   1.256 +
   1.257 +    l3 grep apt-get
   1.258 +
   1.259 +Если вы помните, что начали работу по инсталляции после обеда,
   1.260 +а всё, что было до этого, к делу не относится:
   1.261 +    l3 @14:00:00,$ grep apt-get 
   1.262 +
   1.263 +Если вы помните, что было много инсталляций, но в некоторых из них
   1.264 +вы неправильно указывали имена пакетов, и вы хотели бы оставить
   1.265 +только те из них, которые выполнились успешно:
   1.266 +    l3 grep err=0 grep apt-get
   1.267 +или
   1.268 +    l3 filter err=0&&/apt-get/
   1.269 +или
   1.270 +    l3 filter err=0 grep apt-get 
   1.271 +
   1.272 +=== Привязка ко времени ===
   1.273 +
   1.274 +Вы рассказываете, как настроить какую-то вещь.
   1.275 +Вы хотели бы, чтобы всё, что вы рассказываете,
   1.276 +можно было использовать как основу для составления
   1.277 +более подробного документа.
   1.278 +
   1.279 +Вы используете доску (или графический планшет),
   1.280 +некоторые вещи делаются не в командной строке,
   1.281 +а на экране с графическим интерфейсом,
   1.282 +кроме того ваш голос записывается.
   1.283 +
   1.284 +Вы не можете тратить время на то, чтобы положить скриншоты
   1.285 +в нужное место, но вы можете их сделать.
   1.286 +Аналогично и со скринкастами. Вы можете записывать то,
   1.287 +что вы делаете при подключении к какой-то системе,
   1.288 +но вы не можете выполнять никаких других операций
   1.289 +по обработке записи. Потому что на это просто нет времени.
   1.290 +
   1.291 +Ход вашей работы фиксируется, операции запоминаются,
   1.292 +скриншоты помечаются временными метками.
   1.293 +Аналогично происходит со схемами на доске,
   1.294 +которые фотографируются и представляются в виде помеченных
   1.295 +временными метками файлов.
   1.296 +
   1.297 +После того, как сеанс окончен,
   1.298 +вы получаете его транскрипт, который можно дальше редактировать.
   1.299 +Команды в этом транскрипте сопровождаются специальными якорями,
   1.300 +с помощью которых они привязываются к записанному ранее сеансу.
   1.301 +
   1.302 +В транскрипте вы удаляете лишние команды,
   1.303 +добавляете текст и получаете документ,
   1.304 +который подробно описывает происходившее,
   1.305 +причём при желании вы можете получить недостающую информацию
   1.306 +из архива сделанных ранее операций.
   1.307 +
   1.308 +Туда же, в нужные (соответствующие времени) места, 
   1.309 +автоматически попадают сделанные скриншоты,
   1.310 +скринкасты, фотографии, запись звука.
   1.311 +
   1.312 +
   1.313 +=== Подключение к журналу ===
   1.314 +
   1.315 +Продолжим предыдущий пример.
   1.316 +
   1.317 +Вы прочитали документацию, составленную по описанной выше методике,
   1.318 +и теперь хотите выполнить такую же настройку.
   1.319 +
   1.320 +В обычном случае вы просто копируете команды в свою командную строку
   1.321 +или набираете их заново, с учётом ваших собственных условий.
   1.322 +
   1.323 +Можно значительно ускорить и упростить этот процесс,
   1.324 +а так же уменьшить вероятность ошибки возможной в ходе его выполнения.
   1.325 +
   1.326 +Вы подключаетесь к сделанной записи:
   1.327 +    l3 go http://xgu.ru/l3/option-82
   1.328 +
   1.329 +Все рассмотренные ранее команды становятся доступным.
   1.330 +
   1.331 +Становится доступным продолжение команд (tab completion)
   1.332 +на основе информации, набранной в той работе
   1.333 +и даже больше: вы можете добавить команды
   1.334 +из контекста в историю текущего командного интерпретатора,
   1.335 +как будто вы их сами уже выполняли.
   1.336 +
   1.337 +Автоматически они не добавляются, чтобы не создавать путаницы.
   1.338 +Но вы можете их загрузить:
   1.339 +    l3 % | l3hist
   1.340 +или, если вас интересуют только определённые команды, то с использование интервала,
   1.341 +например:
   1.342 +    l3 @14:00,$ | l3hist
   1.343 +
   1.344 +Вам тогда не нужно будет их заново набирать.
   1.345 +Достаточно прокрутить историю вверх, а потом просто выполнять 
   1.346 +по одной, нажимая ctrl-o, при этом адаптируя к своим условиям.
   1.347 +
   1.348 +Чтобы ещё сильнее сократить себе объём работы,
   1.349 +можно применить процедуру адаптации, которая позволяет
   1.350 +автоматически заменять специфические для процедуры параметры.
   1.351 +
   1.352 +Для этого вы вызываете:
   1.353 +    l3 parameterize
   1.354 +    l3 param  (сокращённо)
   1.355 +которая открывает текстовый редактор, где указывается два столбика параметров:
   1.356 +что заменить и на что заменить.
   1.357 +
   1.358 +Например, пусть в описанном документе используются адреса:
   1.359 +    192.168.15.1
   1.360 +    192.168.15.254
   1.361 +    example.com
   1.362 +
   1.363 +Причём составитель этого документа мог указать, что эти параметры являются специфичными,
   1.364 +а мог не указывать. Если он указал, то совсем хорошо — тогда вам нужно просто пройтись
   1.365 +и добавить справа, на что они должны заменяться в вашем случае.
   1.366 +Если же он не указал, то вам нужно придумать список замен по своему вкусу.
   1.367 +
   1.368 +Вы вводите локализованную версию:
   1.369 +    192.168.15.1        10.0.35.1
   1.370 +    192.168.15.254      10.0.35.254
   1.371 +    example.com         xgu.ru
   1.372 +
   1.373 +Теперь, во всех выводах команды l3 будут исправленные команды
   1.374 +и исправленные результаты их выполнения.
   1.375 +Автопродолжение (tab completion) в шелле уже будет показывать исправленные аргументы.
   1.376 +Историю командного интерпретатора вы тоже можете обновить,
   1.377 +и в ней тогда будут изменённые команды.
   1.378 +
   1.379 +Использовать параметризацию с загрузкой удалённого контекста
   1.380 +настолько логично, что вы можете это сделать одной командой:
   1.381 +    l3 go -p http://xgu.ru/l3/option-82
   1.382 +
   1.383 +