С одной стороны - должна быть гипертекстовая, позволяющая включать в себя любые объекты - с другой стороны - доступная даже из консоли. Последнее, впрочем легко возможно сделать путем присутствия links везде - и хранить все в html. IMHO, в этом плане хорошо сделан Solaris Answer Book. Но переводить маны в подобную форму, полагаю преждевременно... Хотя, кто его знает...

Глупый опрос! Это все равно, что спросить, какой формат изображений Вы предпочитаете: GIF/GIF87a/GIF89a JPEG/JFIF/JIF/JPE BMP/RLE PCX/DCX PNG TIF/TIFF XPM PBM/PGM/PPM DIB TGA MOV CMX/CDR/XAR DAT SMK WMF IFF/ILBM/LBM/Codak Photo CD Конечно JPG! :)

XML (он вроде включает SGML, который включает HTML) .... или я не прав ? ВКЛЮЧИТЕ В СПИСОК XML ! (хотя до конца стандарт этот вроде еще не описан)

Дерьмо. Конечно плайн текст! И в единственной кодировке. Убивать и изничтожать все кодировки кроме одной. И вообще: "самым правильным языком программирования является логика предикатов. Тот, кто работает с другим языком, является идиотом. И вообще, все компьютеры должны работать не в двоичной системе а третичной..."

Согласен с людьми на этой борде, что вопрос некорректно поставлен. Но IMHO TeX -рулез. Те , кто набирал что-либо во одном-известном- -редакторе одной-известной-фирмы, связанное с графиками и рисунками меня поймут.А вообще-то ха-тэ-мэ-ль стал стандартом (преподаватели с родной кафедры, проникшись мощью :)) Mindows D98,и дельфей требуют все программы с выводом резов в этом самом формате,т.к цитирую "... в наше время, когда Internet так бурно развивается... пользователю легче общаться с HTML, нежели с TXT...").That's all folks...

Хотя идеала вероятно не существует, наиболее предпочтительным является тот формат, с которым можно как работать непосредственно так и автоматически преобразовывать в любой (или почти любой) другой формат.

Второму условию наиболее полно отвечает SGML и порожденный от него XML. Средства просмотра XML сейчас бурно развиваются, и он грозит вытеснить HTML.

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

А такого увы нет :((

> XML (он вроде включает SGML, который включает HTML) .... или я не прав ? Не прав. Более того - не в адеквате.

Да.. Сам вопрос глупо поставлен - что значит наиболее правильным? Для просмотра или для базового формата, в котором все будет набиваться и из которого все будет переводиьтся в другие? Какой документации (может, конструкторской)? Далее я считаю что идет речь про доки на софт. Судя по ответу многих (html рулез, или plain text рулез) можно понять, что они поняли как первый вариант. Что касается моего мнения (если трактовать вопрос по второму варианту) - формат должен быть основан на SGML/XML. Возможно DocBook (или свое собственное его надмножество) будет оптимально в 99% случаев - он описывает содержание, а не форму представляения информации - и из этого следует, что они идеально подходят для перегона в другие форматы, более ориентированные на просто отображение/печать и возможно навигацию. Как я понимаю, DTD для DocBook выстрадан годами, и при том умными людьми. Короче, в SGML/XML базированных форматах можно передать информацию об об[екте с произвольной степенью детализации. И конвертить во что-нибудь его очень легко.

> формат должен быть основан на SGML/XML
тогда необходимо определиться с формой представления...
А так, SGML, теоретически хорош.
Инструментов маловато только ИМХО

М-да, дожили. Кому-то удобно документацию в TeX читать :-0 Самостоятельно компилировать код TeX - типа, круто, даже сказать нечего. Или имелось ввиду, что надо получить dvi, а уж оттуда получать более другие форматы, ну и зачем тогда вообще TeX, может сразу выбрать другой формат? Imho, документация должна быть в виде, удобным для быстрого поиска нужной информации, можно конечно и в plain/text и даже в man/groff '/' нажать, но спорить о преимуществах html над оными вряд ли кто в здравом уме станет, это не только ссылки и разбиение доки на подразделы, это еще и возможность сделать текст более удобным для чтения, вставить картинки, вообщем, стоит ли заниматься перечислением достоинств html??? Если документация используется только для печати - то, конечно, ps, вот только зачем нужен компьютер, если в поисках нужной страницы документации вы будете рыться в кипе бумажек. Насчет PDF ничего не скажу, у меня Acrobat Reader, конечно, стоит, но исключительно для просмотра документации, которой, кроме как в PDF, ни в чем больше нет. Ну а в консоли PDF вообще никак не посмотришь, а вот lynx-ом очень даже нормально. А, еще SGML приплели, ну, это, безусловно, один из самых распространенных форматов и вьюеров SGML хоть отбавляй, хоть под X, хоть консольных :-/ Я конечно про SGMl мало знаю, может кто докажет преимущества хранения документации в SGML? Я знаю, что это язык разметки, как и HTML, и возможности его не хуже, но, imho, этот формат как то мало известен, я даже не знаю, чем его посмотреть. Все таки html - общепринятый формат хранения и передачи документации в Internet

Ну для интерактивного просмотра можно генерить html и смотреть их любимым браузером. Технологии как CSS позволят отделить структуру html от его оформления и уменьшить размер полученного html. А чем привлекателен DocBook - это тем, что с помощью него делались доки на весь крутой софт - такой как Motif и CDE допустим (то есть в нем есть все, что могло бы пригодиться при документировании на профессиональном уровне) . Средства для перегона его в html, man/groff и по-моему прямо в ps давно публично доступны. Кстати, все основной формат доков софта для Gnome - DocBook (правда при установке ставится html версия).

То есть все же для интерактивного просмотра - html, ну а для чего же еще нужна документация? Может писать ее кто то будет в SGML, это всем фиолетово, но для чтения в дистрибутив ее лучше класть в html, ну и отдельный пакет для печати - в ps - распечатал и удалил этот пакет. Может для писателей документации удобней SGML, тогда это другое дело. Мне казалось, вопрос стоял о том в каком формате документация удобнее пользователям, то есть для чтения.

Я перепробывал много форматов при подготовке разного рода маниалов, но всетаки HTML на данный момент самый удобный

Смотря для чего...

Для интерактивного использования -- конечно HTML. Всем новым технологиям наподобие XML нужно время чтобы стать стандартом.

Тем не менее, HTML плохо подходит для печатных документов, многие возможности в нём отсутствуют. Поэтому для этой цели лучше всего PS и мне непонятно, почему его объединили с PDF. Кто-нибудь видел принтеры понимающие PDF?

Вопрос задан неправильно, это ясно, чем и спровоцировал кучу бессодержательных по существу откликов. Потребителю документация должна поставляться в том формате, в каком ему удобно читать, то есть лучше во всех сразу, чтобы избежать лишних вопросов. Либо прилагается запускаемый очевидным образом контекстный help viewer. Составителю документации сподручнее взять DocBook или сходное средство (всё равно принцип везде один и тот же --- первична логическая структура документа, а конечный формат и внешний вид определяются backend'ом). Кстати, если кто может четко и ясно объяснить, как с помощью sgmltools v2 (что с jadetex) и последней Dawenport DocBook рожать русские документы --- буду очень благодарен.

Короче, без вопросов - plain\text... Потому что прочитать могут все. Ну, или Маны - там все более красиво выделено: подсветочка и т.д. А так - тока текстом + А почему бы не написать трансятор Любой Формат => plain\text.... То есть этот транслятор не должен ничего, кроме как читать все форматы. В смысле, писать их ему не надо. Ну, например PDF - ну надо позарез прочитать, дк и в тексте мона прочитать...

HTML - однозначно не подходит ни для чего. Он слишком крив, слишком неоднозначна его интерпретация, слишком сложна автоматическая обработка. SGML (да хотя бы linuxdoc DTD) - гораздо предпочтительнее. Особенно если учесть возможность перевода в тот же HTML, в RTF, в TeX...

Кстати, а почему так мало голосов в пользу texinfo? Кто что может на это сказать?

Да потому, что пятое колесо в телеге обычно никто не уважает, даже если оно вполне пригодное. Кстати, lynx отлично справляется с gzip-ованными html-ями. Я думаю было бы здорово научить этому приходящий ему на смену links. Тогда про texinfo вообще можно было бы забыть.

Все же по качеству вывода в разных форматах, по возможностям настройки вывода без изменения текста, по качеству оформления гиперссылок пока у texinfo конкурентов нет. HTML и его позорные смотрелки могут идти в баню: документация хороша лишь на бумаге, об экран никто глаза долго ломать не станет, как бы там все не было красиво оформленно.

SGML/DocBook. Из него легко генерируется HTML, RTF (MSWORD), PLAIN TEXT, TeX, PostScript, PDF, ... -- все, что захочет пользователь. А половина авторов комментариев, похоже, не очень понимает, что такое SGML, DTD и DSSSL.

Блин, Раша - страна смелых новаций и непуганных идиотов 8-)! Есть Linux Documentation Project (LDP) и его официальный формат SGML. Есть IPLabs Linux Team, которая sgml-tools грамотно русифицировала. Есть ГУИ к ним - вордпроцессор LyX... И есть куча рашн линуксоидс, которые на самом популярном Рунет линукс-сайте обсуждают, как бы изобрести по-новой лисапед 8-).

Пардон, у LDP формат не SGML, а linuxdoc, который всего лишь один (и не очень хороший) DTD. Тот же DocBook для документации подходит гораздо лучше, что многие буржуины понимают. К примеру, документаловка на gtk+ именно в нем и сделана. И вообще, почему именно линукс? Документация не только к линуксу нужна, проектики то обычно портабельные... Так что формат документаловки обсуждать можно и нужно.

Блин, ты прав, Петрович, относительно смелых новаций, и про непуганных идиотов отчасти верно. А IPLabs нам не указ, однозначно.

Я - Сергеич 8-)! А без усилий IPLabs многие в Раше прочувствовали бы задницу, юзая только Корел Линдовс И RH нанай-идишн 8-).

LinuxDoc - производная от SGML. Читайте маны 8-).

Не производная от SGML, а эсжемеельный DTD, при чем кривой и для документации хреново подходящий. HINT: html тоже SGML-ный DTD.

"а эсжемеельный DTD"... HINT: хрен редьки слаще!

"при чем кривой "... Чем кривой? HINT2: "причем" пишется слитно!
Возможно, прежде, чем рассуждать о том, в каком формате писать доки,
стоит научиться просто писать ;-)?

Ой. ошибаешься, Сергеич, ой ошибаешься. И IPLabs твой питается теми же редхэтами, да еще и облизывается. Вот если бы твои protege что-нибудь действительно свое, оригинальное сделали, их можно было бы только уважать. А так...

IP LABS отдыхает То что она существует это хорошо, НЕ НАДО ТОЛЬКО говорить что все вокруг пользуются REDHAT/MANDRAKE/COREL... У нас был есть и будет Slackware/ftp.chg.ru/ А что касается формата - то конечно html - не отвечает ВСЕМ требованиям, но тем не менее на сегодня он самый применяемый

Грамотно писать, имея в организме 0.2 лигрыла не очень просто ;)

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

P.S. Про HTML: этот мертворожденный уродец вообще не имеет ни малейшего права называться форматом для документации. И мне крайне редко встречались случаи, когда этот формат использовался. Так что мимо тазика...

Я полностью с этим согласен - html это дикое обобщение - он направлен на описание отображения документа и на его структуру (но структуру обычного текста, такого как статья, письмо и т.д.). Он не способен описать структуру текста как доку на либу с требуемой степенью детализации (конечено на html можно писать <span class=return_type>int</span> и потом вытащить нужную информацию - но это мазохизм).

IMHO, SGML хорош возможностью получения приличного качества документов на разных платформах. И доки набранные в SGML (я использую TEI DTD) можно будет смотреть хоть через 20 лет ( если доживем ;) ).

Это не опрос, а провокация. Комитетам и группам по стандартизации глубоко пофиг, что там СЧИТАЮТ ламеры, не знающие, панимаэшь, что такое SGML. Мнения тут значения не имеют. Вы можете покупать автомобиль любого цвета, при условии что этот цвет черный (Генри Форд).

Все форматы хороши. Одни лучше для одних целей, другие для других.

Идеала нет - это очевидно.

Nu,tipa ja ne so vsemi iz vysheperechislennyh imel vozmozhnost' porabotat' no est' u menja zdorovoe predpochtenie PS/PDF-nu nravits'a on mne i vse. A s mneniem chto HTML hot' i rasprostranen no vse zhe otstoj polnostju soglasen. Ne format a ubozhestvo...

вы чего больные что ли (относится к ламерам, которые указали html)?
sgml является родителем всех markup language,
из него прекрасно все остальные форматы генерятся, но кроме плайн текста
конечно (легче его набить, чем sgml, в этом смысле)
никакого плайн текста, из него ничего больше не получишь удобного.
про кодировки - это конечно руль если будет только кои8, но это не
правильно (к сожалению)
в троичной системе исчисления - это конечно самый лучший способ
хранения данных, однако как его реализовать на железном уровне?

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

Идеала нет не в SGML, а в русифицированных sgmltools для русского же DocBookа. Зайдите на www.opengroup.org и сделайте search для SGML CDE. Будь бы в GNU (Linuhe) такой An enhanced, SGML-based online documentation browser, не было бы ни такого процента педикулеза среди голосующих, ни гнилых базаров про GNOME/KDE...

Да-а, ребятки, разодрались вы в клочья.

Вопрос конечно интересный.... Самый лучший формат это тот который изначально делался для документации. то есть плэйн текст, ман, SGML.
примерно в этом порядке. Я верстаю газеты и знаю, что или пусть лучше текст будет неформатированым чем криво форматированым. Если учесть что доки пишутся хоть и умными людьми но не знакомыми с основами дизайна текста, то становится понятно что сколько ни придумывай форматов, ламеры останутся ламерами и не будут РТФМ. Я считаю что если уж ЛинДокПрож решился собрать все доки по линуху то там должен быль человек(и) которые производят окончательную профессиональную верстку документа и перевод в единый формат. а потом тулза переводит и перекодирует в другую кодировку если надо. или это получится сборище документов разного формата которые кроме как без мата не прочитаешь.
Кстати относительно качества документации и переводов.
Мне иногда охота написать мыло и спросить знает ли автор свой родной язык или нет. Ну такие извраты иногда встречаются.
Переводы я не пользую, но если переводят ПРОМТОм то я могу сказать только одно - а не дать вам билет на эротический пешеходный тур?

Вобщем я за SGML,man,plain txt с автоматической трансляцией.

Удачи - StraX

Я категорически не согласен с plain text. Так как документацию иногда надо не просто ЧИТАТЬ, а еще и ИСКАТЬ в ней что-либо. То есть, должны быть теги логической разметки, дабы можно было автоматично понять, что это - фцнкция, это - тип данных, это - описание к предыдущей функции, и т.д. А вообще очень обидно, что так много идиотов проголосовало за HTML. Надо бы авторам сайта провести по этому поводу разъяснительную работу...

Блин ну очевидно SGML - из него можно "скомпилировать" HTML, pdf, man, rtf и проч. Так например FreeBSD handbook сделана...

Наверное лучше тот формат к которому больше привык...

Slovo of True!

Вообще о чем базар?
Мы говорим о документации вообще или только об on-line документации?

Главное качество хорошей документации (не касаясь ее особенностей ее содержания)наглядность и читабельность.Почти все эти сообщения горланят в одно горло, что ХТМЛ и plain text лучше всех. Не знаю как вы, но я больше трех страниц сплошного текста на экране прочитать никак не могу - спать хочется и глаза слепнут. Утомительно читать бесконочный свиток. Все равно что книгу без полей с мелким шрифтом читать.

Гипертекстовость не так важна, как хорошая верстка.

HTML лишь отчасти может подойти, но его надо правильно оформить, а это геморрой, даже в супер ВИЗИВИГ редакторе. На большом обьеме верстка становится сложной. А потом - совместимость........
В ХТМЛ отсутствует главный момент для хорошего восприятия - страница. Конечно вы можете добавить строчки с цифирьками, но суть не изменится.

Linux man хоть и гипер-, но читается не лучше чистого текста.

Вы все помните слово
КОДИРОВКА

КОДИРОВКА
КОДИРОВКА

КОДИРОВКА

Давайте забудем его. Для книг нет кодировок. Книги читают, а не кодируют. Хватит бреда, принесенного из 80-х годов.

Я точно говорю вам, лучше PDF ничего на сегодняшний день просто нет. У него нет близких аналогов. Ничтожный обьем, полиграфичекое качество, шрифты и картинки в документе, ссылки, индексация. Спрашивайте, чего в нем нет, поточу что в нем есть все!

У вас есть возможность держать все в одном файле или получать по URL
Читатель увидит ровно то, что хотел

Хватит мучать свои глаза - ставьте Acrobat сейчас!

HTML всем хорош, если бы не две проблемы 1 - отсутствие удобной возможности быстрого контекстного поиска, что очень часто необходимо 2 - невозможно красиво распечатать в виде книжки. По╨тому я пока за pdf

Народ, по-моему документация должна служить нескольким целям. Во-первых - это научить человека что-то делать (ставить Linux, поднимать firewall и т. д.). Это как правило большой подробный текст, который несомненно должен быть хорошо оформлен с возможностью получения удобных распечаток. Для этих целей по-моему действительно неплохо подойдет html, хотя можно и tex, ps, ... Насколько я поглядел здесь все спорят именно о такой документации. Однако в системе ОБЯЗАНА быть система помощи, содержащая сжатую, полную, лаконичную информацию (вы например что, наизусть помните все параметры tar, find ...). Эта документация как правило просматривается на экране и ее внешний вид не особо интересен. Важно время поиска нужной страницы и примитивная структура документа. Извините, но man'ы в этом еще никто не переплюнул и не стоит.

Pishite na SGML. Razmechaite i razmechaite. Docbook est', no est' i vpolne ser'yeznyye MIL-STD. I imenno pro dokumentaciyu. Chitaite ikh na lyubom mirror, khotya by ftp.sunet.se/pub/text-processing/SGML/ i poneslas'.

Boys, the man coding is rulezzz!

Вообще-то необходимо выделить несколько форматов.
1) Для возможности читать и печатать в виде книжки. Мое мнение --
это связка TeX-LaTeX с конвертацией в ps или pdf. Оно же (LaTeX)
очень удобно в плане подготовки документации.
2) Для использования на компьютере и возможностей поиска и
гипертекстовых ссылок... Ну, что-то из гипертекстовых
языков. Мне трудно судить какой из них лучше. Лишь бы возможности
отображения сложных конструкций (как в TeX) позволял делать.