>> А то мы не знаем! Я там выразился не совсем верно. Формат изначально онлайновый и чисто этически не принят для оффлайн-документации. Хотя и допускается.
Валве одно время тоже ложили так называемые "previews" для оффлайн документации, и ничего.
После здешних баталий решил я всерьёз обсудить с участниками Оренбургской LUG тему о форматах для документации. Для начала спросил как люди относятся к CHM, ответы были очень суъбективные типа нравится / не нравится". Сегодня один человек написал своё развёрнутое мнение с подробными пояснениями и ссылками, оно стоит того, чтобы его прочитать. Цитирую:
Цитата:
Ну уж раз пошла такая пьянка, позвольте досыпать мои 5 коп. Если продолжать обсуждать сферическую документацию в вакууме, то получается целая куча противоречий.
PDF не самый лучший выбор - это же типографский формат, он предназначен для гарантированного сохранения внешнего вида документа, а для распространения документации к софту это лишнее требование. Наоборот, внешний вид документа должен изменяться в зависимости от условий, в которых документ просматривается: на ЖК панели ли диагональю этак 20-30 дюймов, на нетбуке ли, или вообще в смартфоне, где каждый миллиметр экрана на вес золота. Уж как минимум размер шрифта должен свободно подбираться. И не предлагайте делать зум на документ - приятно ли листать доку не только по вертикали, но и по горизонтали? Смею напомнить так же, что pdf-ка заметно тяжелее текстаря - даже если не жалко трафика и места на носителе, пожалейте хотя бы оперативную память мобильных устройств.
Plain text однозначно самый портабельный (если закрыть глаза на неразбериху в стане кодировок символов) из всех форматов, но и у него есть недостатки, причём серьёзные: ни картинок, ни табличек, ни схем в него толком не включишь. ASCII-арт позволяет отчасти решить эту проблему, но такая вёрстка текста - ад. Да и свёрстанный таким образом текст опять же имеет свою привязку - к количеству столбцов в тексте. Или каждый абзац - одна строка (перенос текстовый редактор делает автоматически, можно выбрать любой шрифт, но никакого ASCII-арта), или все переносы строк в тексте завёрстаны жёстко (ASCII-арт во все поля, но шрифт уже не изменишь, ломай глаза на маленьком экране!). Тоже далеко не везде применимо.
HTML в том или ином виде изначально разрабатывался с учётом того, что просматриваться будет на адовом зоопарке платформ и устройств. Позволяет менять шрифт, включать изображения и иметь гиперссылки в тексте. Надеюсь никто не станет возражать против гиперссылок? Ведь реально полезный инструмент в документации. (Можно возразить, что гиперссылки есть и в pdf, но это не отменяет всех недостатков пдфок, да и переход по гиперссылкам там заметно медленнее). Можно даже свой CSS на чужую HTML-ку натянуть, если очень приспичит - грамотно свёрстанный документ это не изуродует. Но и тут есть целая пачка своих минусов: картинки идут отдельно от самого документа, их легко "посеять" по невнимательности. В chm файл картинки встраиваются, но там то индекс поломается, то кодировки собьются, а причиной тому отсутствие внятной спецификации - это домашняя самоделка Microsoft, и мутирует она как их левой пятке вздумается (точнее, мутировал, т.к. ЕМНИП они и сами забили на этот формат). Из-за последнего фактора ИМХО chm рассматривать как возможный формат совершенно неприемлемо. Остаётся только терпеть отдельные картинки. А там ещё капризы начинаются: "не люблю когда много файлов" или наоборот "нафиг мне один большой файл - я в нём заблужусь и умру с голоду".
Вот.
Не получается как-то единый формат, который всем смог бы угодить. Однако не всё так плохо. Смею напомнить, что мы далеко не первые поднимаем такой вопрос и, чем сотрясать воздух, предлагаю посмотреть что придумали по данному вопросу до нас: "DocBook — это технология разработки документации на основе SGML или XML, позволяющая из единого исходного текста автоматически получать выходные документы в различных форматах (наиболее распространенные — HTML, PDF, HTML Help) и с разными вариантами компоновки и оформления". Подробнее здесь.
Практика включения таких документов в поставку, кстати, уже отработана: обычно включается единый html-документ, размеченный на главы и снабжённый гиперссылками для быстрой навигации. А на сайте проекта для недовольных вывешивается всё остальное: и та же дока, разбитая на самостоятельные главы для удобного чтения онлайн, и та же дока, свёрстанная в PDF для обладателей больших мониторов, мощных машин и быстрых интернетов, и исходник доки, чтобы любой желающий смог прогнать её через любой другой процессор (в ODF или в LaTeX например) или импортнуть в MS Word. Так, например, сделано здесь: http://www.slackbook.org/
К тому же получить из DocBook plain text или man тоже не проблема. Правда, без картинок, но тут уж ничего не поделаешь.
И так, вот готовое решение: бери и пользуйся. Есть ли смысл ломать копья?
Есть уже давно готовое решение - MS Word Doc. Открывается как самом Вордом (что очевидно), так и "голой виндой" (Wordpad), а под линуксом - опенофисом.
SluX писал: "DocBook — это технология разработки документации на основе SGML или XML, позволяющая из единого исходного текста автоматически получать выходные документы в различных форматах (наиболее распространенные — HTML, PDF, HTML Help) и с разными вариантами компоновки и оформления"
Где? Я для твоей же документации старался, народ напряг, человек описал альтернативы, дал ссылки, а ты вот так взял и обосрал... Вот и помогай после этого.
SluX писал: Где? Я для твоей же документации старался, народ напряг, человек описал альтернативы, дал ссылки, а ты вот так взял и обосрал... Вот и помогай после этого.
Да ёлки-палки. Я не имею никакого понятия про DocBook, ODF и прочюю экзотику. И терпеть не могу XML за совершенно уродский синтаксис.
Я понимаю, что для вас он родной и удобный, но мне от этого не легче.
11-10-2010 11:27
