Комментирование в markdown и однострочниках bash файлов

LUKE: Is Perl better than Python?
YODA: No… no… no. Quicker, easier, more seductive.
LUKE: But how will I know why Python is better than Perl?
YODA: You will know. When your code you try to read six months from now.

(c)

Хороший код (и хороший текст) всегда должен быть откомментирован. В последнее время я много пишу на markdown’не, который по ходу дела обрабатывается pandoc’ом и sed’ом, причем все это сведено в один makefile, который со временем разрастается до довольно больших размеров.

  • комментарии в маркдауне

Как проставить комментарии в маркдауне? Вопрос нетривиальный.

Конечно, можно сделать это с помощью html:

<!-- комментарий -->

Однако, читается он плохо, в нем сложно делать моделайны для vim и — самое нехорошее — это то, что он проскакивает сквозь парсер и остается в тексте — а комментарии должны убираться уже на стадии конверсии. В этом плане мне гораздо больше понравился другой вариант, со стековерфлоу:

[//]: # ( Это комментарий! )

[//]: # ( vim: set ft=book conceallevel=2 go-=m go-=T go-=r go-=L go-=e foldlevel=2 comments=:% : )
  • комментарии в башевских однострочниках

Еще интересный вариант — когда комментирование должно приходится рядом с однострочником или длинным-длинным конвейером на bash или sed.

Например, в процессе расчистки того, что получается на выходе после преобразования ipython -> markdown -> html я использую такой вот однострочник:

#!/bin/bash
# зачистка html

filename=$@

cat -s "${filename}" | sed 's-\(<img[^>]*\)\(/>\)-\1 width="99.99%" height="auto" \2-' | sed 's+\(<td\)+\1 border-style="solid" border-width="3" border-color=#000000 +' | sed 's+<meta http-equiv="Content-Style-Type" content="text/css" />++' | sed 's+<p class="caption">png</p>++' | sed  's+\[<matplotlib.*\]++' | sed  's+\<matplotlib.colorbar.*;++' > "${filename}.clean.html"

Он убирает мусор, который получается при конвертировании из ipynb в markdown и подгоняет формат так, чтобы он «лег» в методичку (дальше в игру вступает составной odm-документ, к которому коннектится полученный html, но это — отдельная история).

Менять такой однострочник тяжело — все быстро забывается. Первое, что приходит в голову — разбить его построчно. Длинную строку в баше можно разбить, перенося отдельные строки с помощью обратного слэша (\). И скрипт сразу становится понятнее — по крайней мере визуально.

#!/bin/bash
# зачистка html

filename=$@

cat -s "${filename}"   |
sed 's-\(<img[^>]*\)\(/>\)-\1 width="99.99%" height="auto" \2-'                  \
| sed 's+\(<td\)+\1 border-style="solid" border-width="3" border-color=#000000 +'  \
| sed 's+<meta http-equiv="Content-Style-Type" content="text/css" />++'              \
| sed 's+<p class="caption">png</p>++'                                             \
| sed  's+\[<matplotlib.*\]++'  \
| sed  's+\<matplotlib.colorbar.*;++' \
    > "${filename}.clean.html"

Примерно так же я поступил, когда написал большой скрипт для развертывания openbox’а — там длинный инсталл тоже разбит на разные строки, хотя по сути представляет собой одну длинную строку.

Уже лучше. Но все равно — хочется хоть каких-нибудь пояснений.

Оказывается, код в bash можно разбивать не только обратными слэшами, но вполне допустимо разнести код по пайпам (то есть символ ковейера | сам по себе работает как разбиватель строки), при этом ничего дополнительно не нужно переносить — баш понимает это сам. При этом сразу после пайпа можно указывать коммментарий:

#!/bin/bash
# зачистка html

filename=$@

cat -s "${filename}"                                                            | # убираем лишние пробельные строки
sed 's-\(<img[^>]*\)\(/>\)-\1 width="99.99%" height="auto" \2-'                 | # приводим в чувство ширину картинок
sed 's+\(<td\)+\1 border-style="solid" border-width="3" border-color=#000000 +' | # отрисовываем границы у таблиц
sed 's+<meta http-equiv="Content-Style-Type" content="text/css" />++'           | # надоедливый коммент в libreoffice
sed 's+<p class="caption">png</p>++'                                            | # убираем хвосты ipnb... ->
sed  's+\[<matplotlib.*\]++' |
sed  's+\<matplotlib.colorbar.*;++' \
    > "${filename}.clean.html"

Это очень просто и хорошо в случае, когда однострочник представляет собой конвейер текстовой обработки — тогда его легко разнести по пайпам — один проход конвейера на одну строку. Но длинный однострочник может быть не только конвейером.

Для этого можно использовать еще один способ:

...
sed 's+<p class="caption">png</p>++' `# убираем хвосты ipnb...` |
...

Двойные бэктики (backticks) в bash-скрипте истолковываются как «вставить на это место результат команды, выполненной в шелле». А результатом команды, которая начинается на # — как раз будет комментарий, то есть

`# убираем хвосты ipnb...`

Не вернет вообще ничего. Это позволяет комментировать все, что угодно — особенно удобно это в многострочниках, которые не есть конвейеры.

Вот как у меня инсталлируется «вторая очередь системы» — программы которые не самые важные и которые ставятся по принципу «когда дойдут руки».

Если взять этот однострочник as is — получится такая вот длинная «колбаса»:

#!/bin/bash

sudo apt-get install okular okular-extra-backends recoll antiword catppt djvutxt lyx pstotext unrtf untex wpd2html xls2csv python-chm python-midiutil python-mutagen libimage-exiftool-perl

Если разнести «колбасу» по строкам — получится гораздо лучше:

#!/bin/bash

sudo apt-get install \
    okular okular-extra-backends \
    recoll \
    antiword catppt djvutxt lyx pstotext \
    unrtf untex wpd2html xls2csv \
    python-chm python-midiutil python-mutagen libimage-exiftool-perl

А теперь откомментируем ее «бэктиковыми» комментариями:

#!/bin/bash

sudo apt-get install             `# установка софта второй очереди` \
    okular okular-extra-backends `# ставим okular и бэкэнды к нему` \
    recoll                       `# десктопный поисковик          ` \
    antiword catppt djvutxt lyx pstotext `# конвертеры к recoll'у ` \
    unrtf untex wpd2html xls2csv `# еще конвертеры к recoll'у     ` \
    python-chm python-midiutil python-mutagen libimage-exiftool-perl # просто нужные дополнения

Я не очень старался соблюдать принцип понятности — поскольку случай тривиальный, но как по мне тако скрипт выглядит гораздо читабельнее и юзабельнее, чем просто длинная колбаса.

Реклама

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход / Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход / Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход / Изменить )

Google+ photo

Для комментария используется ваша учётная запись Google+. Выход / Изменить )

Connecting to %s

%d такие блоггеры, как: