Использование asciidoc для документирования проекта

[powerman]

Упс, прошу прощения, совсем забыл. Пару дней назад expire-нулся домен asdfgroup.com, в котором находится мой сайт powerman.asdfgroup.com - владелец домена не уследил, и должен сегодня-завтра домен восстановить. Так что пока последние две ссылки в статье не работают, извините.

[powerman]

Домен восстановили, ссылки должны заработать.

[Wellick]

Всё здорово, но есть пара вопросов:
Как создаются ссылки между разными документами?
Как происходит навигация внутри документа, когда он еще не преобразован в html? Есть ли какие-либо плагины к Vim'у (и к другим текстовым редакторам)?

А в первом приближении всё это очень сильно напоминает один из многочисленных вики-диалектов, типа Textile.

[Wellick]

Если бы еще была интеграция с каким-нибудь редактором, кроме Vim'а (и Emacs'а ;)), я бы, наверное, использовал бы эту штуку для написания постов в блог и для оформления простеньких html-страничек. Чтобы не возиться с html'ем и оформлением напрямую. =)

[powerman]

AsciiDoc не нужна интеграция, он отлично выглядит и пишется/читается даже без подсветки синтаксиса, хоть notepad используйте.

[Wellick]

Я не в смысле подсветки синтаксиса. Хочется, чтобы можно было бы сделать так: написал кусок текста в синтаксисе AsciiDoc, нажал кнопочку - получил этот кусок в буфер обмена уже в виде html-фрагмента. А в идеале еще и вторую кнопочку - для предпросмотра в HTML.
P.S. Я знаю the power of UNIX command line =) Но лениво, ей богу.

[powerman]

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

[Wellick]

Но тогда её надо крутить либо на локальном веб-сервере, либо лезть за этим в интернет, так?

[powerman]

Да, надо локальный веб-сервер. Наша группа, в основном, занимается веб-разработкой, так что локальный вебсервер у всех настроен в любом случае. :)

А вообще никто не мешает повесить в .vimrc hook на запись .txt-файлов в указанном каталоге, который рядом с этим .txt файлом будет в один вызов команды asciidoc класть .html-файл, и вторым вызовом какой-нить утилитки копировать его содержимое в буфер обмена (кстати, а зачем это нужно?).

[Wellick]

Ну вот я и говорю, the power of UNIX command line =)
Нужно, например, чтобы в блог/ЖЖ/комменты к хабру быстро писать красивый html-код.

[powerman]

А что касается "лениво", то мне гораздо проще один раз написать простейший скрипт для выполнения обработок текста одной кнопкой, чем постоянно набирать документацию в формате а-ля docbook.

[Wellick]

Это безусловно.
Мне, конечно, не надо писать docbook'и, но набор текста в html'е удручает.
WISIWYG, зачастую, удручает не меньше.

[powerman]

Ссылки создаются так:

1. К обычным url добавляются скобки а-ля http://ya.ru[] в которых можно написать текст ссылки а-ля http://ya.ru[Яндекс]
2. Ссылки на «соседние» страницы/файлы этой-же доки с помощью схемы «link» а-ля link:otherpage[] или link:subdir/index.html[Описание фичи subdir]
3. Картинки вставляются так image::images/icons/home.png[Alt text]

Навигация до генерации html не происходит никак. Разве что вы пользуетесь достаточно умным текстовым редактором (напр. Vim) и научите его распознавать конструкцию link: для открытия новых файлов. Плагины может и есть, но у меня в них пока потребности не возникало, и я их просто не искал. А вообще это должно очень просто реализовываться, на уровне нескольких строк в .vimrc и без всяких плагинов, я думаю.
Вики действительно напоминает. Но есть и отличия — более интуитивная и простая разметка чем у всех виденных мной вики-диалектов, и возможность работать напрямую с файлами.

[Wellick]

link:otherpage[]

otherpage — это якорь в тексте?
В остальном понятно, спасибо!

[powerman]

Нет, якоря (ссылки внутри текущего документа) делаются иначе, а выше ссылка на файл otherpage.txt лежащий в одном каталоге с текущим файлом.

[makc_de]

Любопытно, насколько различаются наши с Вами требования к системе документирования.

[powerman]

Я именно поэтому начал именно с требований. :)

А какие у Вас требования к системе документирования?

[arty]

кажется, это очень похоже на markdown

[powerman]

Да, такого типа систем некоторое кол-во. Ещё из популярных есть reStructuredText. Как раз эти, и некоторые другие я и сравнивал, когда подбирал для себя систему.

В частности, markdown "заточен" под html, и позволяет делать штуки типа встраивания html-тегов в исходный .txt-файл. А это автоматически означает смешивание структуры документа и его представления, и невозможность его корректно перегнать в тот же docbook.

[aeriman]

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

[winzard]

javadoc?

[Dogen]

DocBook может и стандарт де-факто, только LaTeX стандартнее ;)