http://habrahabr.ru/rss/blogs/i_am_advertising/41211/ ru editor@habrahabr.ru habrahabr.ru Sun, 21 Mar 2010 19:02:55 GMT http://habrahabr.ru/ http://habrahabr.ru/i/logo.gif http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1520279 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1520279 sphinx.pocoo.org
Нет визуального редактора, но зато я могу полностью котролировать визуальное представление, список выходных форматов больше. А главное исходник каждой статьи это отдельный текстовый файл, в котором только контент без представления, потому я могу держать проэкт в mercurial или svn репозитарии и видеть изменения обычным diff-ом. Отдельные файлы позволяют работать над документацией совмесно нескольким людям. Для редактрирования RST пользуюсь e-TextEditor или Vim.
Я дописал несколько разширений для форматирования рисунков при конвертировании в html, а также вставку swf, с Help & Manual такое пока невозможно, только планируется интеграция с SandCastle.
Но в любом случае выбор конкертного инструмента зависит от вашей задачи.
Думаю интерактивную справку по продукту в chm или Help2 нужно в Help & Manual или RoboHelp делать, а вот html или pdf, а также документацию по проєкту для разработчиков мне удобне делать на Sphinx.]]> Wed, 08 Apr 2009 11:11:33 GMT stoune http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1520231 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1520231 Они очень хорошо аргументировали свою позицию и я с ними согласен. LaTEX хорош для создания печатной документации, но сейчас печатают мало зато в онлайне кусок примера посмотреть это часто, а ещё ссылки и много другого.
Потому на входе как раз у них ReSructured Text, а на выходе формат какой задашь тот же LaTEX.]]> Wed, 08 Apr 2009 10:58:23 GMT stoune http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1037361 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1037361
>Т. е. по-вашему ваша же тулза больше «вдохновляет» чем doxygen

Ну это уже вопрос философский — его сложно обсуждать в споре. Моя тулза другая. Она отличается от генераторов документации по API на основе кода. С помощью нее можно сделать опрятную книжку и не только про API.

Зато конечно моя тулза не умеет генерить документацию по API, да это и не нужно, т. к. и так есть такие инструменты.

Так, что вдохновляет, да :)]]> Sun, 12 Oct 2008 14:24:04 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1037281 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1037281
например вот этот пример меня совсем не вдохновил:
www.php.net/~helly/php/ext/spl/]]> Sun, 12 Oct 2008 13:11:54 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1019015 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1019015
Про волнистую линию хорошая мысль, спасибо.

"«Оформление и настройки". Эта кавычка, для многих привычный значок, заменяющий стрелочку. Это стрелка назад и название предыдущей главы (в докбуке есть такой элемент, когда вы строите html-книгу). Возможно стоит нарисовать стрелочку картинкой или другим значком.

Мой инструмент, кстати, не полный конкурент докбуку. Они пересекаются, но не совпадают. Вот смотрите, какая идеология у моего BullDoc:

1. Есть исходник документации в некотором формате (это обязательно должен быть текстовый файл). Пока это html, с некоторыми служебными вставками. Но в планах сделать поддержку маркдаун, вики, и приколоться — сделать поддержку docbook (взять парсер вот из этого проекта wiki.php.net/doc/phd)

2. Этот исходник при отображении прогоняется через соответствующий парсер. Пока это только html-примитивный парсер.

3. Из того что получилось делается книжка с оглавлением, меню разделов, стрелками вперед-назад и предметным указателем. Причем понятно, что неудобно после каждой правки собирать весь проект, чтобы посмотреть, что получилось. Для этого есть возможность смотреть это через веб сервер, без полной пересборки. В комментариях есть похожий проект, касающийся именно докбука, — чтобы набирать не в XML, а в чем-то, что легко переносится в докбук, и чтобы смотреть результат онлайн без полной пересбоки.

Поэтому Докбук и BullDoc вполне могут мирно дружить.]]> Sun, 05 Oct 2008 06:39:48 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1018658 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1018658
По поводу скринов, просто можно было их обрезать чем-то типа волнистых черт, чтобы буквы не резать посередине, смотрится неопрятно. Обычно во всех продвинутых программах для снятия скриншотов есть такие возможности.

Сайт, кстати, понравился, быстрый и симпатичный :). Одно замечание только, что сразу бросилось в глаза: "«Оформление и настройки". В заголовках по одной кавычке напрягает немного, чувство незавершенности вызывает :). Лучше бы или вообще без кавычек, или с двух сторон.

В общем, удачи! Приятно, что адекватно восприняли мой комментарий, я на самом деле без суровости, а наоборот, с лучами добра :). Сейчас перечитал, подумал, что немного грубовато :). Но тут уж такие дела, вы пиарите свой инструмент, а я свой, докбук :). Чем больше народу с ним будет возиться, тем всем будет проще =).]]> Sat, 04 Oct 2008 20:15:04 GMT akeepaki http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1018619 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1018619
Каринки я обвел рамками через стили, но добрый хабр стили повырезал.

Картинки можно было делать скриншотами, отмасштабированными к 500 пикселам, но хотелось, чтобы текст был виден. Возможно это неудачно. Что-то пробовал так и эдак и не очень получилось видимо.

Суть же постарался изложить :)

Докбук хорош :) но с ним есть определенные неудобства, выше в обсуждении это упоминается. Конечно, как универсальный формат Докбук очень удобен и конкурировать с ним нет смысла.

Однако с точки зрения удобства для себя, я не поленился и написал свой инструмент.]]> Sat, 04 Oct 2008 19:43:32 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1018596 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1018596
А по сути дела, приятно, что какие-то движения есть, но я как-то на докбук перешел и норм. Поначалу пришлось, конечно, покопаться, зато после созданиях всех нужных шаблонов и батников для автопарсинга стало хорошо. А XML каждый техрайтер из отдела может править в своем любимом редакторе, никого ни к чему не принуждаем. Ведь отличное знание текстового редактора (набор привычных макросов, хоткеев, темплейтов) — это огромный бонус в производительности техписа.
]]> Sat, 04 Oct 2008 19:18:30 GMT akeepaki http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1007126 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1007126
Код форматировать LaTex может при помощи пакета Listings. А html из него можно получать при помощи Hevea.

С другой стороны, LaTex, конечно, скорее предназначен для статей и книжек, чем для документации.]]> Tue, 30 Sep 2008 16:32:50 GMT juliette http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1007019 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1007019
Да я вроде понимаю, что DocBook идеологически правильный стандарт. И долгое время я на него смотрел, но что-то не сложилось у меня с ним.

Может еще сложится :)]]> Tue, 30 Sep 2008 15:38:51 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006981 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006981
DocBook это стандарт, достаточно зрелый и правильный, вполне подходящий для такого рода документации. И для DocBook есть куча разнообразного софта. Единственный недостаток (IMHO) DocBook — в нём неудобно писать текст — решается использованием для написания текста AsciiDoc. А когда текст уже написан и отконвертирован в DocBook, то корректировать текст по мелочи можно и в самом DocBook, чтобы не морочиться повторной конвертацией из AsciiDoc (особенно если после конвертации в DocBook этот DocBook активно довёрстывался с помощью софта для DocBook).

А возможность получить из AsciiDoc сразу html — это удобно для публикации небольших документов, для предварительного просмотра в процессе подготовки большого документа (чтобы не возиться с DocBook пока документ не будет готов), и для wiki.

Насколько я понимаю, Ваш BullDoc по назначению ближе к DocBook. Возможно, Вам стоит более внимательно поглядеть на DocBook (держа в голове что подсветку синтаксиса можно получить автоматом при конвертации из AsciiDoc в DocBook, и что с DocBook надо поработать через специальный софт, а не ручками с XSLT).]]> Tue, 30 Sep 2008 15:26:53 GMT powerman http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006929 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006929
ну а так вопрос свелся к подсвечивать код или нет. он наверное философский.]]> Tue, 30 Sep 2008 15:10:56 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006899 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006899 Тем более, автоподстветка изредка ошибается, для фрагментов шанс ошибочного расцвечивания ещё выше.]]> Tue, 30 Sep 2008 15:03:12 GMT Busla http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006846 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006846 Tue, 30 Sep 2008 14:44:38 GMT VSOP_juDGe http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006745 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006745
А не подскажете где взять такие макросы?]]> Tue, 30 Sep 2008 14:06:16 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006744 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006744
Этот прект и Ваше его использование крайне близко к тому, для чего писался BullDoc. Однако все же это взгляды под разными углами.

Аскидок больше нацелен на удобную разметку. И ваш скриптик дает возможность предпросмотра страницы без полной сборки всего документа.

На выходе в родном варианте генерится монолитный html файл (если говорить о выводе в html), а это не всегда удобно. Прочие приемы требуют еще и наличия докбучных инструментов.

Мой же проект предполагает выносить парсеры разметки в плагины. И нацелен на сборку статической книжки из многих html файлов. И на сборку CHM. Понятное дело, что и монолитный файл документации для распечатки тоже создается. Т. е. моя программа это не рендерер, а собиратель и построитель навигации, предметного указателя, и пр. Всяких парсеров я прикручу еще. Очень хочется маркдаун прикрутить в первую очередь.]]> Tue, 30 Sep 2008 14:05:13 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006739 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006739 Tue, 30 Sep 2008 14:02:56 GMT VSOP_juDGe http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006657 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006657
1. Когда встает вопрос в чем писать пользовательскую документацию, один их ответов бывает Word.

2. Если мы пишем документацию для проектов веб-разработки, то там часто используются примеры кода. Особенно если это документация для разработчиков (которые тоже пользователи системы). Код удобно подсвечивать.

3. В Word нет подсветки кода.]]> Tue, 30 Sep 2008 13:36:16 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006618 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006618 Tue, 30 Sep 2008 13:25:01 GMT Busla http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006443 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006443
У латеха язык свой. Его учить надо? Надо. А с полпинка не выучишь. Он на выходе хтмл дает статический? А я хочу именно этого. Он CHM на выходе может? А мне надо. А над ё мне ударение не надо. И формулы я в своей программерской деятельности не набираю, а вот код подсвеченный в документации мне нужен. И его Латехом я наверное тоже не смогу обеспечить, так?

Чтобы посмотреть, что получится я каждый раз компилить должен, так ведь? А это не удобно.

Ну так получается Латех для моей задачи НЕ ГОДИТСЯ. Хотя он и уруливает, и DVI рулез.]]> Tue, 30 Sep 2008 12:14:38 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006404 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006404 А в Вашем случае, Вы можете поставить знак ударения над буквой «ё»? ]]> Tue, 30 Sep 2008 11:57:52 GMT trak http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006059 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006059
Что такое подсветка синтаксиса. Когда Вы пишите программу или просто html файл, удобно, когда текстовый редактор подсвечивает ключевые слова и скобки разным цветом. Также и читать удобнее программу, если она подсвечена. Например вот так:
bulldoc.ru/screenshots/highlight.png]]> Tue, 30 Sep 2008 09:54:53 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006011 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1006011 подсветка синтаксиса такая в документации. Может стоило подробнее описать проблему/задачу вцелом?
]]> Tue, 30 Sep 2008 09:39:41 GMT Busla http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005541 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005541
Конечно решаемо все :) Но иногда хочется удобства.]]> Tue, 30 Sep 2008 06:39:02 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005388 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005388
Еще раз спасибо за коментарии.]]> Tue, 30 Sep 2008 04:41:11 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005379 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005379 Tue, 30 Sep 2008 04:37:31 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005350 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005350
Да и просто если бы Вы зашли ко мне на сайт, там навигация и от корня достаточно прозрачная: Software->asciidoc.cgi.]]> Tue, 30 Sep 2008 04:04:01 GMT powerman http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005324 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005324
Ваша ссылка на asciidoc. Большое за нее спасибо! Если бы я прочитал этот Ваш топик, с большой вероятностью я бы допиливал asciidoc под себя. Он очень близок к тем задачам, что решает мой BullDoc (ну при наличии cgi-шки, которой наверное нет в открытом доступе. Выложили бы — спрос бы был наверное).]]> Tue, 30 Sep 2008 03:09:05 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005319 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005319
Но лично мне удобнее html, главное чтобы редактор удобный был, в котором пишу.]]> Tue, 30 Sep 2008 02:56:08 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005199 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005199 Использование asciidoc для документирования проекта]]> Mon, 29 Sep 2008 22:45:35 GMT powerman http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005156 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1005156 Mon, 29 Sep 2008 22:00:06 GMT egorinsk http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004802 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004802 Mon, 29 Sep 2008 19:29:41 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004798 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004798 Mon, 29 Sep 2008 19:26:42 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004787 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004787
1. Действительно работа с документацией в SVN была очень сильным мотивом взяться за эту работу.

2. Насчет хаченья скрипта для смены оформления. Тут все культурненько — есть темы. Хачить не надо.

3. Орфография ну да-да. Мы опенофисом просто втупую вычитываем перед релизом. Но подозреваю, что можно копать в сторону ispell и интеграции с текстовым редактором.

4. Я пока не улез особо в дебри. По крайней мере HTML вполне читаем… Кстати, кстати… про TeX я очень даже подумываю :))))

5. Против священной коровы и характера все-таки хочется надеяться что поможет постоянный code-review, и таки проект обвешан модульными тестами.

Вернетесь к перлу :)))) sure.]]> Mon, 29 Sep 2008 19:23:18 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004777 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004777 Mon, 29 Sep 2008 19:19:08 GMT Pik http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004751 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004751 Mon, 29 Sep 2008 19:10:54 GMT fantaseour http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004712 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004712 Покрутите и вот это (freeware version) helpinator может еще какие идеи придут к вам.]]> Mon, 29 Sep 2008 18:54:05 GMT jasiejames http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004676 http://habrahabr.ru/blogs/i_am_advertising/41211/#comment_1004676 Mon, 29 Sep 2008 18:38:50 GMT DIDJER