Кто в чем пишет документацию на ПО?

пишу в LaTeX

Мы пишем книжку в docbook (хотя это нечерезруки и я бы предпочёл чистый LaTeX), документацию по модулям в doxygen.

http://gwyddion.net/documentation/

LaTeX

notepad же, ну

Docbook + Serna

texinfo, markdown

У нас не на ПО, но все же - в ворде пишут. Пишут, плачут, потому что ворд все погнаит, и все равно пишут, ибо ворд - это круто.

только dev-python/sphinx! tex и docbook для робатов

Да. Задолбали эти ССЗБ, которые только в «ворде» документацию принимают. Если бы не долбаные госсайты и прочие вантузятники, я бы идиотский LO выкинул вообще к чертовой матери.

У нас это дело доходит до полнейшего маразма. Я не говорю о том, что все перацкое, не, это уже черт с ним (из непирацкого у нас только моя убунта), но убивает сам кретинизм ситуации.

Пример - надо написать отчем по проведенным на стендах работах. Отчет требуют «по госту» - рамочка, все дела. И в ворде. Набираение простейшего отчета в этом гогне растягивается на месяц, ибо то рамочку не вснадалить так, чтобы не сместился текст, то не выровнять текст, потому что ворд хочет сделать по-другому, то еще подобная ерунда. Самый смак - когда уже все готово, но один из «ведущих спецов», который комп видел только на картинках, говорит «Надо вот тут *тыкает пальцем или карандашом в монитор, да так, что там чуть ли не дырка остается* добавить пару абзацев». И все. Бедный парнишка, который набирает эту чехарду, опять неделю долбается с вордом, пытаясь заставить это дело выглядеть так, что было нормально. Потом, когда приходит время печатать эту мутатень, ворд опять радует идиотизмом, при печати неведомым образом сдвигая рамочки куда попало и делая из норального документ какую-то чушь.

А все почему? Потому что начальству подавай в *.doc, и никак иначе.

Самое веселое, что все это можно сделать в КОМПАСе, в котором есть текстовый режим - набрал текст, он его сам рахобьет по страницам, влепит рамки, гостовый шрифт и все сделает чики-пуки.

Хорошо, что я не занимаюсь таким идиотизмом, тьфутьфутьфу...

*Выдохнул*

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

Да я вот только позавчера долбался со скотским LO: оформлял ТЗ для торгов. Бодался с ним полтора дня, чтобы картинки не съезжали, куда не надо, отображались в нужном порядке, да чтобы таблицы выглядели по-человечески.

В латехе бы за пару часов набрал, откомпилил - и выставил pdf…

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

А в LO, если делаешь документ, его ни в коем случае нельзя закрывать, пока не распечатаешь: при следующем открывании рискуешь получить кактус!

Самое веселое, что все это можно сделать в КОМПАСе, в котором есть текстовый режим - набрал текст, он его сам рахобьет по страницам, влепит рамки, гостовый шрифт и все сделает чики-пуки.

Если просто текст - то и в LO делать элементарно: рамочка впихивается в колонтитул, и все путем.

Да я вот только позавчера долбался со скотским LO: оформлял ТЗ для торгов. Бодался с ним полтора дня, чтобы картинки не съезжали, куда не надо, отображались в нужном порядке, да чтобы таблицы выглядели по-человечески.

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

А в LO, если делаешь документ, его ни в коем случае нельзя закрывать, пока не распечатаешь: при следующем открывании рискуешь получить кактус!

ИМХО, можно сохранить его в пдф, тогда останется неломаемый бэкап =)

Если просто текст - то и в LO делать элементарно: рамочка впихивается в колонтитул, и все путем.

Не, там текст, формулы, картинки, еще какая-то хрень.

Были попытки заюзать doxygen - вещь годная, но требующая настройки + правильно оформленных комментов в коде. Поскольку я ленив и разбираться в настройках не хочу, то пишу ручками в LaTeX. Да и прототип ф-ии втыкается копипастом без проблем, проблема связно изложить зачем он нужен и что делает, и проиллюстрировать это изложение картинками...

ИМХО, можно сохранить его в пдф, тогда останется неломаемый бэкап =)

И нередактируемый.

Ну хотя бы неломаемый.

Познакомьте того парнишку со связкой LaTeX+latex2rtf

Вантузятники на 146% предсказуемы: парнишка сделает огромные глаза и с воплем «аааа, хулиганы зрения лишают!» останется на своем говноворде.

Не, он тоже ворд любит. Ему это, видать, удовольствие доставляет.

И да, latex2rtf - жесточайшее дерьмо, как и любой другой конвертер латеха в прочие форматы. Работает только с ограниченным количеством стилей, никаких вам бибтехов и т.п.

Ага, ну как-то так, да =)

У них, похоже, как у макофилов, какой-то то ли зонд, то ли врожденный мазохизм.

Идиотизм врожденный у них.

Помню, как один чувак на работе захотел линукс попробовать, прочитал где-то о нем. Пристал ко мне. Ну, я ему посоветова мандриву, думаю «юзерфрендли, все дела». Дык он умудрился поломать таблицу разделов на винте, потом сказал, что линукс гогно и больше он его трогать не будет.

И да, latex2rtf - жесточайшее дерьмо

Не спорю. Но из всех вариантов «сделать в ворде» это самый приемлемый. Остальные, по скромному личному опыту, еще хуже;-)

В ВУЗе, когда у меня потребовали автореферат в .doc-формате (!), я распустил imagemagic'ом pdf на jpeg'и, воткнул их в openoffice и сохранил как .doc ☺

Мы тоже так когда то делали, но это уже полное извращение...

Зато получается красиво.

У нас не на ПО, но все же - в ворде пишут.

Ага, я вот тоже утром закончил писать документацию в ворде. Чувствую себя идиотом^W^Wчто нужно что-то менять.

emacs muse

Зато получается красиво.

Не верю, честно говоря. Как же размытые ШГ в JPEG?

А вообще интересный вопрос — можно ли в .doc делать как PDF.

То есть, примерно, по пунктам:

1. Встроенные шрифты — загнать прямо в .doc нормальный шрифт с точно известной метрикой.

2. Абсолютное позиционирование всего. С учетом 1., я могу теперь буквы ставить ровно так, как хочу.

3. Всякие колонтитулы, таблицы и прочее при таком подходе идут нафиг — пусть их генерит отдельно из примитивов на каждую страницу TeX или еще кто-нибудь. Будет много места занимать, ну и что, винты-то большие.

Насколько я понимаю, такого пока еще нет, но весьма интересно, можно ли такое сделать. Я понимаю, что можно просто в документ воткнуть в виде OLE что угодно (хоть просмотрщик PDF), но вроде как опять же сам код в документ не запихнешь, да и с переносимостью станет явно хуже.

Microsoft Office 2003

Так из ворда можно сохранить в пдф же и уже будет пофиг в чем ее делали.

noweb же :)

1. Встроенные шрифты — загнать прямо в .doc нормальный шрифт с точно известной метрикой.

Кажется, можно: http://support.microsoft.com/kb/290952

Тогда, вроде как, какие-то шансы есть.

Вот с п. 2 пока непонятно — ясно, что использовать вордовскую тайпсетилку мы не хотим, хотим теховскую, т.е. каждую буковку надо отдельно рисовать. Вроде как в ворде это можно только text frames делать, но это небось оверхед очень большой.

Есть же там какая-то векторная графика? Может, перевести все в кривые и в таком виде засунуть? А под низ положить невидимый тот же текст в нормальном виде, чтобы выделять-копировать можно было.

Так из ворда можно сохранить в пдф же и уже будет пофиг в чем ее делали.

Вопрос я том, чтобы сэкономить на процессе"делания". Я попробовал работать в этом вашем ворде - это же беспросветный песец.

А у вас есть какие-то выставленные сверху требования к оформлению документации?

Как же размытые ШГ в JPEG?

Зато форматирование не теряется.

можно ли в .doc делать как PDF

Нет, конечно. WYSIWYG никогда не позволит получить быстро хорошо отформатированные документы.

Советую сравнить pdf, полученный «из ворда», с pdf'ом, полученным pdflatex'ом.

Различие видно даже неискушенному пользователю.

haddock / latex

latex + haddock

docstrings for API

latex for manuals

Так на будущее спрошу. Каковы успехи использования latex2rtf?

Ответ для разных языков будет отличаться. Или ты ищешь универсальное средство?

Помимо всего уже вышеуказанного использую Redmine - wiki, чисто для утилитарных вещей: дать ссылку в wiki девелоперам, тестерам вместе с указанием «RTFM» :)

WYSIWYG никогда не позволит получить быстро хорошо отформатированные документы.

Я же не предлагаю писать документы в msword. Я обсуждаю возможность генерации .doc в стиле pdf из того же tex.

А вот это - да, было бы удобно.

Так на будущее спрошу. Каковы успехи использования latex2rtf?

При некоторых танцах с бубном - вполне. Конвертил отчеты по 200 страниц, с формулами и графиками.

А у вас есть какие-то выставленные сверху требования к оформлению документации?

Даже если есть, они звучат как «должно быть в вордЕ».

Ответ для разных языков будет отличаться.

Разве? Если ответ "(latex || Docbook) && Doxygen", то это универсально.

Или ты ищешь универсальное средство?

Ну, если оно работает для Си и Python, мне хватит.

Ну, doxygen для JS не подходит, так что не универсально и печально.

docstrings for API

А чем извлекаешь докстринги из исходников в печатную документацию?