Comments 50
habracut!
Как по мне, так Help&Manual удобнее (ИМХО).
Спасибо за наводку покручу.
Интересно.
Покрутите и вот это (freeware version) helpinator может еще какие идеи придут к вам.
Покрутите и вот это (freeware version) helpinator может еще какие идеи придут к вам.
А я как раз из Help & Manual ушол. На sphinx.pocoo.org
Нет визуального редактора, но зато я могу полностью котролировать визуальное представление, список выходных форматов больше. А главное исходник каждой статьи это отдельный текстовый файл, в котором только контент без представления, потому я могу держать проэкт в mercurial или svn репозитарии и видеть изменения обычным diff-ом. Отдельные файлы позволяют работать над документацией совмесно нескольким людям. Для редактрирования RST пользуюсь e-TextEditor или Vim.
Я дописал несколько разширений для форматирования рисунков при конвертировании в html, а также вставку swf, с Help & Manual такое пока невозможно, только планируется интеграция с SandCastle.
Но в любом случае выбор конкертного инструмента зависит от вашей задачи.
Думаю интерактивную справку по продукту в chm или Help2 нужно в Help & Manual или RoboHelp делать, а вот html или pdf, а также документацию по проєкту для разработчиков мне удобне делать на Sphinx.
Нет визуального редактора, но зато я могу полностью котролировать визуальное представление, список выходных форматов больше. А главное исходник каждой статьи это отдельный текстовый файл, в котором только контент без представления, потому я могу держать проэкт в mercurial или svn репозитарии и видеть изменения обычным diff-ом. Отдельные файлы позволяют работать над документацией совмесно нескольким людям. Для редактрирования RST пользуюсь e-TextEditor или Vim.
Я дописал несколько разширений для форматирования рисунков при конвертировании в html, а также вставку swf, с Help & Manual такое пока невозможно, только планируется интеграция с SandCastle.
Но в любом случае выбор конкертного инструмента зависит от вашей задачи.
Думаю интерактивную справку по продукту в chm или Help2 нужно в Help & Manual или RoboHelp делать, а вот html или pdf, а также документацию по проєкту для разработчиков мне удобне делать на Sphinx.
Попробуйте сравнить не с обычными редакторами текста, а с вики-движками, например.
Их явно не хватает в обзоре.
Их явно не хватает в обзоре.
Это не совсем обзор :) это пиар :)
Однако таки да. Про Вики забыл. Более того, опыт работы с dokuwiki при написании документации тоже сыграл в пользу написания рекламируемой программы.
Вот, что я имею против вики:
а) Самое главное. Я не могу в вики разделять документацию по релизам. Вот сделал я релиз 1.0, и начал работать над 2.0. при этом в 1.0 продолжают вноситься фиксы, что-то правится в доке. А в 2.0 меняется интерфейс и дока меняется сильно. В вики такое разделение делать неудобно. А в случае, если твои текстовые файлы с документацией лежат прямо в svn, все прозрачно и удобно. Я всегда могу сделать чекаут нужной версии документации, хоть первой ветки, хоть второй.
б) Механизма выделения файлов контента из программы вики. Чтобы бэкапиить перекидывать с локально машины на сервер и обратно. Каждый раз приходится упаковывать всю папку с вики.
в) Все-таки в вики мне не хватает свободы писать в HTML. Хочется как-то иногда отформатировать, но натыкаешься на ограничения.
Однако таки да. Про Вики забыл. Более того, опыт работы с dokuwiki при написании документации тоже сыграл в пользу написания рекламируемой программы.
Вот, что я имею против вики:
а) Самое главное. Я не могу в вики разделять документацию по релизам. Вот сделал я релиз 1.0, и начал работать над 2.0. при этом в 1.0 продолжают вноситься фиксы, что-то правится в доке. А в 2.0 меняется интерфейс и дока меняется сильно. В вики такое разделение делать неудобно. А в случае, если твои текстовые файлы с документацией лежат прямо в svn, все прозрачно и удобно. Я всегда могу сделать чекаут нужной версии документации, хоть первой ветки, хоть второй.
б) Механизма выделения файлов контента из программы вики. Чтобы бэкапиить перекидывать с локально машины на сервер и обратно. Каждый раз приходится упаковывать всю папку с вики.
в) Все-таки в вики мне не хватает свободы писать в HTML. Хочется как-то иногда отформатировать, но натыкаешься на ограничения.
я думаю, это зависит от реализации движка
в каком-то это может быть (специально не изучал)
в каком-то это может быть (специально не изучал)
такое разделение по релизам в вики, о котором вы говорите, сделать элементарно. Просто для каждого релиза нужно делать отдельный документ, т. о. внутри каждого документа (релиза) будет история фиксов относящая только к данному релизу. вот.
и вот тут давнишняя беседа с авторами LIMB-porject об использовании wiki. Т. е. у них есть свой подход к проблемам, которыми я не доволен.
forum.agiledev.ru/index.php?t=msg&th=1168&start=0&
но это уж очень сырой материал.
forum.agiledev.ru/index.php?t=msg&th=1168&start=0&
но это уж очень сырой материал.
Несколько лет назад использовался самописный гавнаскрипт на перле. Из кучи папочек файлами, ресурсами, ${разметкой} и ${макросами} делается LATeX и HTML.
Из приятностей:
1) наотличненько сочитается с SVN и eclipse, оформление меняется не зависимо от контента (путем хачения скрипта)
2) Удобно включать всякие полезности вида картинок-диаграмок-сырцов (все с версиями!)
3) Снапшоты, версии и бранчи делаются на уровне SVN вместе с сырцами. Хотя такого чтобы на бранч документацию писали отдельную моя седая голова не припомнит ;-)
4) 0-install, перлоскрипт прилетает по «svn get...».
5) типографский вывод для печатной доки.
6) один исходник для разных форматов (ну, партитура для танца с бубном прилагается)
Из неприятностей похода:
1) Нет визуального редактирования (техрайтера мелко колбасило при виде эклипса, с подавляемыми рвотными позывами)
2) Проверка орфографии штатная из эклипса (не удобно, как результат туча очепяток). Почти помог проход ispell.
3) Генеряемое не отличается читабельностью на уровне кода. Периодически бывают косяки вида ускакавших хрен знает куда иллюстрации в DVI, overfull/underfull в пол-страницы, косяки в HTML коде и прочее. Так как доку генеряют за 3 часа до релиза, обычно это довольно стрессовые моменты.
4) Перлоскрипт становится священной коровой, обретает интеллект, характер, астральное тело и начинает требовать жертвоприношений.
С того момента были предприняты попытки писать доки в sharepoint-е (стартует на ура, но получение печатной копии — непреодолимая проблема, снапшот для релиза — делается через API большой геморрой). В итоге чуется вернемся к перлу. Вопрос по сей день открыт.
Из приятностей:
1) наотличненько сочитается с SVN и eclipse, оформление меняется не зависимо от контента (путем хачения скрипта)
2) Удобно включать всякие полезности вида картинок-диаграмок-сырцов (все с версиями!)
3) Снапшоты, версии и бранчи делаются на уровне SVN вместе с сырцами. Хотя такого чтобы на бранч документацию писали отдельную моя седая голова не припомнит ;-)
4) 0-install, перлоскрипт прилетает по «svn get...».
5) типографский вывод для печатной доки.
6) один исходник для разных форматов (ну, партитура для танца с бубном прилагается)
Из неприятностей похода:
1) Нет визуального редактирования (техрайтера мелко колбасило при виде эклипса, с подавляемыми рвотными позывами)
2) Проверка орфографии штатная из эклипса (не удобно, как результат туча очепяток). Почти помог проход ispell.
3) Генеряемое не отличается читабельностью на уровне кода. Периодически бывают косяки вида ускакавших хрен знает куда иллюстрации в DVI, overfull/underfull в пол-страницы, косяки в HTML коде и прочее. Так как доку генеряют за 3 часа до релиза, обычно это довольно стрессовые моменты.
4) Перлоскрипт становится священной коровой, обретает интеллект, характер, астральное тело и начинает требовать жертвоприношений.
С того момента были предприняты попытки писать доки в sharepoint-е (стартует на ура, но получение печатной копии — непреодолимая проблема, снапшот для релиза — делается через API большой геморрой). В итоге чуется вернемся к перлу. Вопрос по сей день открыт.
Большое спасибо за комментарий.
1. Действительно работа с документацией в SVN была очень сильным мотивом взяться за эту работу.
2. Насчет хаченья скрипта для смены оформления. Тут все культурненько — есть темы. Хачить не надо.
3. Орфография ну да-да. Мы опенофисом просто втупую вычитываем перед релизом. Но подозреваю, что можно копать в сторону ispell и интеграции с текстовым редактором.
4. Я пока не улез особо в дебри. По крайней мере HTML вполне читаем… Кстати, кстати… про TeX я очень даже подумываю :))))
5. Против священной коровы и характера все-таки хочется надеяться что поможет постоянный code-review, и таки проект обвешан модульными тестами.
Вернетесь к перлу :)))) sure.
1. Действительно работа с документацией в SVN была очень сильным мотивом взяться за эту работу.
2. Насчет хаченья скрипта для смены оформления. Тут все культурненько — есть темы. Хачить не надо.
3. Орфография ну да-да. Мы опенофисом просто втупую вычитываем перед релизом. Но подозреваю, что можно копать в сторону ispell и интеграции с текстовым редактором.
4. Я пока не улез особо в дебри. По крайней мере HTML вполне читаем… Кстати, кстати… про TeX я очень даже подумываю :))))
5. Против священной коровы и характера все-таки хочется надеяться что поможет постоянный code-review, и таки проект обвешан модульными тестами.
Вернетесь к перлу :)))) sure.
Вот когда научатся подтвержать подленность документа без возможности копирования «росписи» вот тогда и будет шык а пока очередная куча плагинов и добавлнию ещё одной скорости к велосипеду.
Мой отец писал софтину ComponentOne Doc2Help, это немного другое но того-же направления =)
Советую прикрутить Textile, это по моему самая удобная штука для разметки. она удобне HTML
Писать в HTML… ой. Вот, гляньте на такой подход: Использование asciidoc для документирования проекта
Для меня было не очень важно какой язык разметки будет использоваться. Я специально сделал API для класса форматирования, чтобы цеплять потом разные разметки. Сколько «удобных» разметок я не пробовал, лично мне роднее html. Но это лично мое предпочтение.
Ваша ссылка на asciidoc. Большое за нее спасибо! Если бы я прочитал этот Ваш топик, с большой вероятностью я бы допиливал asciidoc под себя. Он очень близок к тем задачам, что решает мой BullDoc (ну при наличии cgi-шки, которой наверное нет в открытом доступе. Выложили бы — спрос бы был наверное).
Ваша ссылка на asciidoc. Большое за нее спасибо! Если бы я прочитал этот Ваш топик, с большой вероятностью я бы допиливал asciidoc под себя. Он очень близок к тем задачам, что решает мой BullDoc (ну при наличии cgi-шки, которой наверное нет в открытом доступе. Выложили бы — спрос бы был наверное).
Как это нет в открытом доступе? Перечитайте последний абзац статьи, там ссылка на мой сайт. А на сайте внизу ссылка на cgi-шку (тоже в последнем абзаце).
Да и просто если бы Вы зашли ко мне на сайт, там навигация и от корня достаточно прозрачная: Software->asciidoc.cgi.
Да и просто если бы Вы зашли ко мне на сайт, там навигация и от корня достаточно прозрачная: Software->asciidoc.cgi.
Вот жеж слепой. Прочитал статью, а ссылки пропустил.
я внимательно посмотрю этот инструмент, и обязательно сошлюсь на Ваш сайт в разделе Аналоги.
Еще раз спасибо за коментарии.
Еще раз спасибо за коментарии.
Бегло посмотрел.
Этот прект и Ваше его использование крайне близко к тому, для чего писался BullDoc. Однако все же это взгляды под разными углами.
Аскидок больше нацелен на удобную разметку. И ваш скриптик дает возможность предпросмотра страницы без полной сборки всего документа.
На выходе в родном варианте генерится монолитный html файл (если говорить о выводе в html), а это не всегда удобно. Прочие приемы требуют еще и наличия докбучных инструментов.
Мой же проект предполагает выносить парсеры разметки в плагины. И нацелен на сборку статической книжки из многих html файлов. И на сборку CHM. Понятное дело, что и монолитный файл документации для распечатки тоже создается. Т. е. моя программа это не рендерер, а собиратель и построитель навигации, предметного указателя, и пр. Всяких парсеров я прикручу еще. Очень хочется маркдаун прикрутить в первую очередь.
Этот прект и Ваше его использование крайне близко к тому, для чего писался BullDoc. Однако все же это взгляды под разными углами.
Аскидок больше нацелен на удобную разметку. И ваш скриптик дает возможность предпросмотра страницы без полной сборки всего документа.
На выходе в родном варианте генерится монолитный html файл (если говорить о выводе в html), а это не всегда удобно. Прочие приемы требуют еще и наличия докбучных инструментов.
Мой же проект предполагает выносить парсеры разметки в плагины. И нацелен на сборку статической книжки из многих html файлов. И на сборку CHM. Понятное дело, что и монолитный файл документации для распечатки тоже создается. Т. е. моя программа это не рендерер, а собиратель и построитель навигации, предметного указателя, и пр. Всяких парсеров я прикручу еще. Очень хочется маркдаун прикрутить в первую очередь.
Путь AsciiDoc заключается в том, что когда Вам понадобится вёрстка и вывод в CHM/PDF/etc. Вы для этого будете использовать богатейшие возможности DocBook.
DocBook это стандарт, достаточно зрелый и правильный, вполне подходящий для такого рода документации. И для DocBook есть куча разнообразного софта. Единственный недостаток (IMHO) DocBook — в нём неудобно писать текст — решается использованием для написания текста AsciiDoc. А когда текст уже написан и отконвертирован в DocBook, то корректировать текст по мелочи можно и в самом DocBook, чтобы не морочиться повторной конвертацией из AsciiDoc (особенно если после конвертации в DocBook этот DocBook активно довёрстывался с помощью софта для DocBook).
А возможность получить из AsciiDoc сразу html — это удобно для публикации небольших документов, для предварительного просмотра в процессе подготовки большого документа (чтобы не возиться с DocBook пока документ не будет готов), и для wiki.
Насколько я понимаю, Ваш BullDoc по назначению ближе к DocBook. Возможно, Вам стоит более внимательно поглядеть на DocBook (держа в голове что подсветку синтаксиса можно получить автоматом при конвертации из AsciiDoc в DocBook, и что с DocBook надо поработать через специальный софт, а не ручками с XSLT).
DocBook это стандарт, достаточно зрелый и правильный, вполне подходящий для такого рода документации. И для DocBook есть куча разнообразного софта. Единственный недостаток (IMHO) DocBook — в нём неудобно писать текст — решается использованием для написания текста AsciiDoc. А когда текст уже написан и отконвертирован в DocBook, то корректировать текст по мелочи можно и в самом DocBook, чтобы не морочиться повторной конвертацией из AsciiDoc (особенно если после конвертации в DocBook этот DocBook активно довёрстывался с помощью софта для DocBook).
А возможность получить из AsciiDoc сразу html — это удобно для публикации небольших документов, для предварительного просмотра в процессе подготовки большого документа (чтобы не возиться с DocBook пока документ не будет готов), и для wiki.
Насколько я понимаю, Ваш BullDoc по назначению ближе к DocBook. Возможно, Вам стоит более внимательно поглядеть на DocBook (держа в голове что подсветку синтаксиса можно получить автоматом при конвертации из AsciiDoc в DocBook, и что с DocBook надо поработать через специальный софт, а не ручками с XSLT).
Мне, как человеку далёкому от труда технических писателей, совершенно непонятно, что это за подсветка синтаксиса такая в документации. Может стоило подробнее описать проблему/задачу вцелом?
Тут надо было выбрать о чем писать. Моя цель была наиболее полно представить инструмент тем, кому он по моему мнению нужен, — т. е. программистам и техписателям, близким к программистам. Слишком много текста в пиарной статье это ИМХО не гуд.
Что такое подсветка синтаксиса. Когда Вы пишите программу или просто html файл, удобно, когда текстовый редактор подсвечивает ключевые слова и скобки разным цветом. Также и читать удобнее программу, если она подсвечена. Например вот так:
bulldoc.ru/screenshots/highlight.png
Что такое подсветка синтаксиса. Когда Вы пишите программу или просто html файл, удобно, когда текстовый редактор подсвечивает ключевые слова и скобки разным цветом. Также и читать удобнее программу, если она подсвечена. Например вот так:
bulldoc.ru/screenshots/highlight.png
А как связана подсветка синтаксиса кода, пользовательская документация и Word?!
Это вопрос на миллион долларов!
1. Когда встает вопрос в чем писать пользовательскую документацию, один их ответов бывает Word.
2. Если мы пишем документацию для проектов веб-разработки, то там часто используются примеры кода. Особенно если это документация для разработчиков (которые тоже пользователи системы). Код удобно подсвечивать.
3. В Word нет подсветки кода.
1. Когда встает вопрос в чем писать пользовательскую документацию, один их ответов бывает Word.
2. Если мы пишем документацию для проектов веб-разработки, то там часто используются примеры кода. Особенно если это документация для разработчиков (которые тоже пользователи системы). Код удобно подсвечивать.
3. В Word нет подсветки кода.
По-моему, LaTex всех уруливает. Другое дело, что при работе с ним надо думать головой, это-же не «висифиг».
А в Вашем случае, Вы можете поставить знак ударения над буквой «ё»?
А в Вашем случае, Вы можете поставить знак ударения над буквой «ё»?
Ну это хум хау. Кому уруливает, а кому нет.
У латеха язык свой. Его учить надо? Надо. А с полпинка не выучишь. Он на выходе хтмл дает статический? А я хочу именно этого. Он CHM на выходе может? А мне надо. А над ё мне ударение не надо. И формулы я в своей программерской деятельности не набираю, а вот код подсвеченный в документации мне нужен. И его Латехом я наверное тоже не смогу обеспечить, так?
Чтобы посмотреть, что получится я каждый раз компилить должен, так ведь? А это не удобно.
Ну так получается Латех для моей задачи НЕ ГОДИТСЯ. Хотя он и уруливает, и DVI рулез.
У латеха язык свой. Его учить надо? Надо. А с полпинка не выучишь. Он на выходе хтмл дает статический? А я хочу именно этого. Он CHM на выходе может? А мне надо. А над ё мне ударение не надо. И формулы я в своей программерской деятельности не набираю, а вот код подсвеченный в документации мне нужен. И его Латехом я наверное тоже не смогу обеспечить, так?
Чтобы посмотреть, что получится я каждый раз компилить должен, так ведь? А это не удобно.
Ну так получается Латех для моей задачи НЕ ГОДИТСЯ. Хотя он и уруливает, и DVI рулез.
Наверное потому Python перевёл свою документацию с LaTEX.
Они очень хорошо аргументировали свою позицию и я с ними согласен. LaTEX хорош для создания печатной документации, но сейчас печатают мало зато в онлайне кусок примера посмотреть это часто, а ещё ссылки и много другого.
Потому на входе как раз у них ReSructured Text, а на выходе формат какой задашь тот же LaTEX.
Они очень хорошо аргументировали свою позицию и я с ними согласен. LaTEX хорош для создания печатной документации, но сейчас печатают мало зато в онлайне кусок примера посмотреть это часто, а ещё ссылки и много другого.
Потому на входе как раз у них ReSructured Text, а на выходе формат какой задашь тот же LaTEX.
Эту статью писал техписатель? Как-то слабовато верится. Или написал за 5 минут, на коленке. Оформление кривоватое, суть как-то расплывчата. Картинки без рамок и как-то неудачно вырезаны. Брр…
А по сути дела, приятно, что какие-то движения есть, но я как-то на докбук перешел и норм. Поначалу пришлось, конечно, покопаться, зато после созданиях всех нужных шаблонов и батников для автопарсинга стало хорошо. А XML каждый техрайтер из отдела может править в своем любимом редакторе, никого ни к чему не принуждаем. Ведь отличное знание текстового редактора (набор привычных макросов, хоткеев, темплейтов) — это огромный бонус в производительности техписа.
А по сути дела, приятно, что какие-то движения есть, но я как-то на докбук перешел и норм. Поначалу пришлось, конечно, покопаться, зато после созданиях всех нужных шаблонов и батников для автопарсинга стало хорошо. А XML каждый техрайтер из отдела может править в своем любимом редакторе, никого ни к чему не принуждаем. Ведь отличное знание текстового редактора (набор привычных макросов, хоткеев, темплейтов) — это огромный бонус в производительности техписа.
Эту статью писал автор программы :)
Каринки я обвел рамками через стили, но добрый хабр стили повырезал.
Картинки можно было делать скриншотами, отмасштабированными к 500 пикселам, но хотелось, чтобы текст был виден. Возможно это неудачно. Что-то пробовал так и эдак и не очень получилось видимо.
Суть же постарался изложить :)
Докбук хорош :) но с ним есть определенные неудобства, выше в обсуждении это упоминается. Конечно, как универсальный формат Докбук очень удобен и конкурировать с ним нет смысла.
Однако с точки зрения удобства для себя, я не поленился и написал свой инструмент.
Каринки я обвел рамками через стили, но добрый хабр стили повырезал.
Картинки можно было делать скриншотами, отмасштабированными к 500 пикселам, но хотелось, чтобы текст был виден. Возможно это неудачно. Что-то пробовал так и эдак и не очень получилось видимо.
Суть же постарался изложить :)
Докбук хорош :) но с ним есть определенные неудобства, выше в обсуждении это упоминается. Конечно, как универсальный формат Докбук очень удобен и конкурировать с ним нет смысла.
Однако с точки зрения удобства для себя, я не поленился и написал свой инструмент.
Хорошо :).
По поводу скринов, просто можно было их обрезать чем-то типа волнистых черт, чтобы буквы не резать посередине, смотрится неопрятно. Обычно во всех продвинутых программах для снятия скриншотов есть такие возможности.
Сайт, кстати, понравился, быстрый и симпатичный :). Одно замечание только, что сразу бросилось в глаза: "«Оформление и настройки". В заголовках по одной кавычке напрягает немного, чувство незавершенности вызывает :). Лучше бы или вообще без кавычек, или с двух сторон.
В общем, удачи! Приятно, что адекватно восприняли мой комментарий, я на самом деле без суровости, а наоборот, с лучами добра :). Сейчас перечитал, подумал, что немного грубовато :). Но тут уж такие дела, вы пиарите свой инструмент, а я свой, докбук :). Чем больше народу с ним будет возиться, тем всем будет проще =).
По поводу скринов, просто можно было их обрезать чем-то типа волнистых черт, чтобы буквы не резать посередине, смотрится неопрятно. Обычно во всех продвинутых программах для снятия скриншотов есть такие возможности.
Сайт, кстати, понравился, быстрый и симпатичный :). Одно замечание только, что сразу бросилось в глаза: "«Оформление и настройки". В заголовках по одной кавычке напрягает немного, чувство незавершенности вызывает :). Лучше бы или вообще без кавычек, или с двух сторон.
В общем, удачи! Приятно, что адекватно восприняли мой комментарий, я на самом деле без суровости, а наоборот, с лучами добра :). Сейчас перечитал, подумал, что немного грубовато :). Но тут уж такие дела, вы пиарите свой инструмент, а я свой, докбук :). Чем больше народу с ним будет возиться, тем всем будет проще =).
Спасибо за лучи добра.
Про волнистую линию хорошая мысль, спасибо.
"«Оформление и настройки". Эта кавычка, для многих привычный значок, заменяющий стрелочку. Это стрелка назад и название предыдущей главы (в докбуке есть такой элемент, когда вы строите html-книгу). Возможно стоит нарисовать стрелочку картинкой или другим значком.
Мой инструмент, кстати, не полный конкурент докбуку. Они пересекаются, но не совпадают. Вот смотрите, какая идеология у моего BullDoc:
1. Есть исходник документации в некотором формате (это обязательно должен быть текстовый файл). Пока это html, с некоторыми служебными вставками. Но в планах сделать поддержку маркдаун, вики, и приколоться — сделать поддержку docbook (взять парсер вот из этого проекта wiki.php.net/doc/phd)
2. Этот исходник при отображении прогоняется через соответствующий парсер. Пока это только html-примитивный парсер.
3. Из того что получилось делается книжка с оглавлением, меню разделов, стрелками вперед-назад и предметным указателем. Причем понятно, что неудобно после каждой правки собирать весь проект, чтобы посмотреть, что получилось. Для этого есть возможность смотреть это через веб сервер, без полной пересборки. В комментариях есть похожий проект, касающийся именно докбука, — чтобы набирать не в XML, а в чем-то, что легко переносится в докбук, и чтобы смотреть результат онлайн без полной пересбоки.
Поэтому Докбук и BullDoc вполне могут мирно дружить.
Про волнистую линию хорошая мысль, спасибо.
"«Оформление и настройки". Эта кавычка, для многих привычный значок, заменяющий стрелочку. Это стрелка назад и название предыдущей главы (в докбуке есть такой элемент, когда вы строите html-книгу). Возможно стоит нарисовать стрелочку картинкой или другим значком.
Мой инструмент, кстати, не полный конкурент докбуку. Они пересекаются, но не совпадают. Вот смотрите, какая идеология у моего BullDoc:
1. Есть исходник документации в некотором формате (это обязательно должен быть текстовый файл). Пока это html, с некоторыми служебными вставками. Но в планах сделать поддержку маркдаун, вики, и приколоться — сделать поддержку docbook (взять парсер вот из этого проекта wiki.php.net/doc/phd)
2. Этот исходник при отображении прогоняется через соответствующий парсер. Пока это только html-примитивный парсер.
3. Из того что получилось делается книжка с оглавлением, меню разделов, стрелками вперед-назад и предметным указателем. Причем понятно, что неудобно после каждой правки собирать весь проект, чтобы посмотреть, что получилось. Для этого есть возможность смотреть это через веб сервер, без полной пересборки. В комментариях есть похожий проект, касающийся именно докбука, — чтобы набирать не в XML, а в чем-то, что легко переносится в докбук, и чтобы смотреть результат онлайн без полной пересбоки.
Поэтому Докбук и BullDoc вполне могут мирно дружить.
oxygen + генераторы?
Можете показать хотя бы одну приличную документацию для конечного пользователя, сделанную с помощью этого инструмента, чтобы можно было пользоваться, как книжкой, а не как черновиком?
например вот этот пример меня совсем не вдохновил:
www.php.net/~helly/php/ext/spl/
например вот этот пример меня совсем не вдохновил:
www.php.net/~helly/php/ext/spl/
www.stack.nl/~dimitri/doxygen/results.html
Т. е. по-вашему ваша же тулза больше «вдохновляет» чем doxygen?
Т. е. по-вашему ваша же тулза больше «вдохновляет» чем doxygen?
Ну по ссылке я увидел аналогичное тому, что «меня не вдохновляет». Это справка по API, а не документация. И к тому же ее надо писать внутри кода, чего я не люблю.
>Т. е. по-вашему ваша же тулза больше «вдохновляет» чем doxygen
Ну это уже вопрос философский — его сложно обсуждать в споре. Моя тулза другая. Она отличается от генераторов документации по API на основе кода. С помощью нее можно сделать опрятную книжку и не только про API.
Зато конечно моя тулза не умеет генерить документацию по API, да это и не нужно, т. к. и так есть такие инструменты.
Так, что вдохновляет, да :)
>Т. е. по-вашему ваша же тулза больше «вдохновляет» чем doxygen
Ну это уже вопрос философский — его сложно обсуждать в споре. Моя тулза другая. Она отличается от генераторов документации по API на основе кода. С помощью нее можно сделать опрятную книжку и не только про API.
Зато конечно моя тулза не умеет генерить документацию по API, да это и не нужно, т. к. и так есть такие инструменты.
Так, что вдохновляет, да :)
Sign up to leave a comment.
BullDoc — система разработки документации