Как вы относитесь к формату CHM?

[slux]

Собрался один человек писать документацию к своему игровому движку (пока win only), задумался в каком виде её писать и куда. И заваязалась у меня с толпой виндузятников дискуссия "CHM vs. PDF", вот и захотелось обсудить это здесь. Я выступаю за PDF и против CHM. Вобщем, лично мне CHM кажется чем-то ужасно глючным, и вообще вражеским и неимеющим права существовать в кроссплатформенном мире. Особенно чётко запомнилась пара моментов с открытием нужных вещей в этом формате через Okular и xChm, остался очень неприятный осадок. То кодировка неверная и сменить не получается, то фон глючит и размазывается между текстом... Да и не является он стандартом для документации, вроде бы.

А что думаете вы?

[Yakoff]

  Оба формата мне нравятся. CHM, все-таки тоже имеет право на существование. Много документации для 1С в этом формате, но вот у меня есть справочник такой, без которого никак. Работать удобно. Все же не упомнишь. Поиск и разбивка по темам сделаны грамотно. Минус - в linux читается не очень, перепробовал кучу ПО, результат - слабый. И тут двоякое мнение:
а) Не удачный формат
б) Разработчики ПО реализовали плохо свой продукт
  Каждый принимает то мнение, которое ему ближе. И тут ничего пока не сделаешь (личное ИМХО).

[Adept]

PDF - открытый международный OSI-формат. CHM - нет. Думаю, этим все сказано

[alex_storm]

Например я сталкивался с данным форматом только однажды, когда качал справочник операндов для C++, а так кругом сплошной ПДФ =) Так что против сказать ничего не могу, но и за лапки тянуть не буду

[Zerocool]

chm мне лично не особо нравится, а pdf, если он адекватно реализован, имхо, заткнёт его за пояс
Другой разговор, что в win семействе chm можно запустить без установки стороннего совта, pdf же вроде как либо через ридеры читать, либо через браузеры со спец. молудями, а если у тебя нет интернета, то это становится небольшой, но довольно гемороной проблемой ...

Если софт ориентирован на то, что наличие интернета будет почти в 100% случаев, то я бы выбрал pdf, в противном случае (и без желания портирования на nix системы), имхо, целесообразнее использовать виндовые плюшки, тобишь chm ...

Хотя, как вариант, монжо собрать и "вашим и нашим", т.е. 1 версию, в pdf, другую в chm, многие генераторы умеют сохранять как туда, так и сюда, главное, правильно организовать сам по себе этот гайд

[slux]

Если софт ориентирован на то, что наличие интернета будет почти в 100% случаев, то я бы выбрал pdf

Тогда я бы вообще выбрал онлайн-вики, что и предложил им самым первым вариантом.

[Yakoff]

Если софт ориентирован на то, что наличие интернета будет почти в 100% случаев, то я бы выбрал pdf

Тогда я бы вообще выбрал онлайн-вики, что и предложил им самым первым вариантом.

  Ну, так тоже нельзя. Наличие документации в комплекте с ПО - признак хорошего тона. Она должна быть, хотябы минимально. Вики можно как более углубленный вариант. Обходить стороной пользователей (имеется ввиду не только этот конкретный случай, но и остальные) без связи тоже нельзя. Их возможно мало, но они есть. Возможно у многих "отсутствие инета" временное явление, но это не должно ограничить пользователя.

p.s. А если реализовать справку ввиде HTML страничек? И пусть они в директории с ПО будут расположены. Браузеры вроде в любой ОС умолчально есть (если движок потом и под другую плотформу выйдет).

[Zerocool]

CHM - компилированный html документ же, или меня прёт?

[Adept]

ага. но, емнип, своеобразным образом скомпилированный

[slux]

Угу...

[user_anonymous]

Лично я крайне негативно отношусь к CHM
Доки должны быть в виде plain text, html и pdf Вот такое вот ИМХО.

[Zerocool]

plan text неудобен, на мой взгляд, кучи html-ок, имхо, тоже раздражают
Так что из твоего списка, по моему мнению, остаётся только pdf

[wilful]

Смотря какой plan text, зато можно открыть где и когда угодно.
Плюсую за plan text, как вариант хранения небольшой и не сложной инфы.

CHM минусую потому как то индексы полетят, то вообще не откроется, в общем не сложилось и не нада.

pdf он и в Африке pdf. Все зависит от области применения, понятное дело что в простом тексте не напишешь сложных формул и таблиц, зато latex+pdf отлично справляется =) Ну и в консоли открыть pdf проблематично, весят много, нужен спец софт, тут спасает просто текст

├───────┼────────┼─────────┼─────────┤
│ чем       │не            │ таблица   │ ?              │
| многие | редакторы | так умеют | и не только|
+--------+-----------+-----------+-------------+
см. man mysql для примера.

Для сабжа конечно не пойдет, но я храню многие записи например вот так. Для "одного человека" думаю лучшим вариантом был бы pdf.

[LexxTheFox]

plan text неудобен, на мой взгляд, кучи html-ок, имхо, тоже раздражают
Так что из твоего списка, по моему мнению, остаётся только pdf

Ну уж раз пошла такая пьянка, позвольте досыпать мои 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 тоже не проблема. Правда, без картинок, но тут уж ничего не поделаешь.

И так, вот готовое решение: бери и пользуйся. Есть ли смысл ломать копья?

[Zerocool]

Ну, по факту, Lex ты разложил недостатки, но реальной альтернативы всё нет, ибо DocBook - всего лишь инструментарий для создания описанных выше сабжев ...

По поводу xml - с тем же успехом можно использовать fb2 и кучу других реализаций.
rtf, кстати, тоже сильно распространен (хоть и проприентарен) К слову, он даже более суров, чем банальный plantext и, ко всему прочему, если мне не изменяет память, у него насильно можно указать кодировку текста, так что таких косяков, как с обычным текстом там не будет + оформление

Да, бОльший вес, но сейчас мы не живём во времена диалапа и скоростей в 28 килобит, чтобы уж совсем так серьёзно мелочиться ...

Списки форматов можно вспоминать до бесконечности и у каждого есть свои плюсы и минусы, но мы говорим немного о другом ...

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

[LexxTheFox]

Списки форматов можно вспоминать до бесконечности и у каждого есть свои плюсы и минусы, но мы говорим немного о другом ...

Ну как же? О выборе формата и говорим. По-моему уместно рассмотреть преимущества и недостатки имеющихся вариантов. Я всего лишь веду к тому, что универсального формата, который устроит всех, как бы нет. Вот и предлагаю решение, которое в силу своих возможностей проблему решает. У посетителя есть выбор в каком виде качать доку. По-моему хорошее решение.

[Zerocool]

Ну, допустим, тот же OOo может сохранять в pdf и другие форматы, а он почти есть у каждого (офис, кстати, тоже вроде как ум еет, как и читать всякого рода xml, тот же fb2 щёлкает как орешки)

Я просто не вижу смысла в размещении у себя на системе лишнего ПО, с функциями которого справляется другое ...

Но это мелочи

[slux]

офис, кстати, тоже вроде как ум еет

Твоя фраза выглядит так, будто опенофис это не офис, а единственный офис только тот, о котором ты говоришь. Подозреваю, что говоришь об MSO.

[LexxTheFox]

Я просто не вижу смысла в размещении у себя на системе лишнего ПО, с функциями которого справляется другое ...

Извини, ты документацию для людей писать собрался или капризничать по поводу "хочу - не хочу что-то ставить на свой компьютер"? В последнем случае никаких вопросов о выборе формата вообще стоять не должно - пиши в чём нравится, а люди пусть как хотят изворачиваются. Кто захочет, тот прочтёт.

[Zerocool]

slux я говорю о том, что большинство пользователей винды подразумевает под словом офис и да, ты прав, я говорю об  MS Office

Кстати, doc формат тоже распространен и его, насколько я помню, из коробки wordpad читает под виндой, так что тоже неплохой вариант

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