Как лучше всего написать документацию, ориентированную как на HTML, так и на PDF?

Вы можете сделать шаг назад и использовать что-то вроде DocBook и выполнить рендеринг в PDF через LaTeX и HTML прямо из файлов DocBook. В качестве альтернативы Adobe Technical Communication Suite (Framemaker) позволит вам использовать единый источник документа в форматах PDF и HTML. См. эта публикация для краткого изложения различных систем технической документации.

Да, конвертеры LaTeX-to-HTML раньше были отстойным (вы, наверное, пробовали LaTeX2HTML), но в последнее время они стали лучше. Tex4ht легко настраивается и создает хороший XHTML + CSS. См. Также другие преобразователи.

Вы также можете использовать Docbook, если можете писать в нем. Существуют конвертеры из DocBook как в HTML, так и в LaTeX (или напрямую в PDF); примером последнего является dblatex.

Смотрите этот пост: LaTeX против Docbook.

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

Если вы настаиваете на преобразовании латекса в html, постарайтесь использовать ограниченное подмножество, которое можно преобразовать в разумных пределах.

PlasTeX выглядит как хороший конвертер латекса в html, хотя сам я его не пробовал.

Мой друг Роб Фелти написал в блоге сообщение, восхваляющее его достоинства: http://blog.robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter/

AsciiDoc выглядит интересной возможностью.

Раньше я использовал TeXinfo, и он неплохо справляется. Вот пример: http://yootles.com/api. Я бы предпочел придерживаться LaTeX, а не использовать другой язык.

Латекс? Шутки в сторону? Я не знал, что кто-то за пределами академических кругов все еще использует его. Я бы выбрал HTML, который вы можете сохранить как PDF из веб-браузера. Если вам действительно нужен какой-то продвинутый типографский материал, используйте Word - у него есть способ сохранения в HTML (вероятно, не такой чистый, как хотелось бы), и вы можете сохранить в формате PDF с помощью бесплатного плагина (загружаемого отдельно) .

О, и я бы не стал использовать такие вещи, как InDesign - их слишком много. Кроме того, не беспокойтесь об оплате Acrobat Professional - доступно множество бесплатных решений.

Это личный выбор, но латекс теоретически идеален, но на практике это заноза в заднице. Я использую редактор VS.NET HTML + редактирование необработанного HTML, когда мне это нужно.

Поэтому я считаю, что лучше всего использовать HTML-редактор WSIWYG. Вы всегда можете использовать простой инструмент для преобразования его в PDF, и вы всегда можете редактировать HTML, когда вам нужно что-то продвинутое. Кроме того, когда вам нужно, его проще подключить к Интернету.

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

После многих лет мучений и нескольких фальстартов я собираюсь вернуться к этому и собираюсь попробовать Сфинкс. Он может генерировать HTML или LaTeX из Восстановленный текст.

Я надеюсь, что это будет гораздо более «легкий» вариант, чем полный DocBook, но со многими преимуществами.

Для документирования кода я также рекомендую Sphinx. ReStructured Text удобен тем, что он удобен для чтения и в некоторой степени размечен в виде открытого текста и может хорошо выполнять преобразование в HTML и PDF. Мне по-прежнему нравится LaTeX в некоторых вещах. Мы с женой используем LaTeX, чтобы написать рождественское письмо, которое мы рассылаем обычной почтой. Версия в формате pdf довольно навороченная, с двумя столбцами, верхним и нижним колонтитулами. Версия html проще. Конвертирую пластексом. Примеры здесь: http://fedibblety.com/annualReports

Я не думаю, что какой-либо двоичный формат является хорошим выбором (Word) для любого документа, который вы, возможно, захотите прочитать через 10 лет. Это одна из приятных особенностей LaTeX.

Если ничего не помогает, вы можете взять конвертер LaTeX в XML и написать простую таблицу стилей XSLT, чтобы преобразовать ее в HTML, или создать таблицу стилей CSS и напрямую прикрепить ее к файлу XML.

Мы использовали WebWorks ePublisher (www.webworks.com), который предлагает как несколько форматов с одним источником (мы используем Word), так и возможность вывода во многие форматы вывода (мы выводим в Adobe PDF и в онлайн-справку (.CHM) .

Прочтите о формате EPUB. Его формат электронной книги. http://en.wikipedia.org/wiki/EPUB

Поскольку в ответе с упоминанием Asciidoc было несколько коротких примеров, вот некоторые из вещей, которые вы ищете:

• pdf, созданный с помощью Asciidoc
• шпаргалка рядом с разметкой Asciidoc и результатом html.
• список публикаций, выполненных с использованием Asciidoc, включая книги O'Reilly и документацию git (чтобы увидеть оба конца шкалы пользователя).

Мы столкнулись с этой проблемой в академическом проекте, в котором использовалось программное обеспечение Eclipse, и мы использовали plastex для преобразования Latex в HTML и Eclipse Help. Заставить его работать было довольно сложно, но конечный результат выглядит действительно неплохо. Здесь вы можете увидеть все три версии:

http://handbook.event-b.org/

Кроме того, поскольку это открытый проект, доступен код (сценарии сборки). У нас есть система непрерывной сборки (Jenkins), которая перестраивает все, когда регистрируется новый Latex. Это особенно приятно, поскольку участникам не нужно устанавливать набор инструментов в свои системы. Они просто проверяют новый латекс и проверяют на сервере, правильно ли был создан HTML. Источники:

http://sourceforge.net/p/rodin-b-sharp/svn/HEAD/tree/trunk/Handbook/org.rodinp.handbook.feature/

С уважением, Майкл

У меня недостаточно моментов, чтобы прокомментировать, но, чтобы подкрепить ответ пластекса, вот обновленная ссылка на пример пластекса:

http://robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter