Как лучше всего написать документацию для HTML и PDF?
Конвертеры латекса в HTML, которые я видел в прошлом, были довольно ужасными. Редактирование необработанного html - это не весело и, похоже, плохо переводится на печатную страницу. Как другие решают эту проблему? Ссылки на примеры (как PDF, так и HTML) были бы отличными.
Добавлено: Еще один похожий вопрос был только что задан:
Какой язык форматирования я должен использовать для проектной документации
16 ответов
Для документирования кода я также рекомендую Sphinx. ReStructured Text удобен тем, что его можно прочитать и несколько разметить в виде открытого текста, и он может хорошо выполнять преобразование в html и pdf. Мне все еще нравится LaTeX для определенных вещей. Мы с женой используем LaTeX, чтобы написать наше рождественское письмо, которое мы рассылаем обычной почтой. PDF-версия довольно необычная, с двумя столбцами, верхними и нижними колонтитулами. HTML версия проще. Я конвертирую с помощью пластекса. Примеры здесь: http://fedibblety.com/annualReports
Я не думаю, что какой-либо двоичный формат является хорошим выбором (Word) для любого вида документа, который вы хотели бы прочитать через 10 лет. Это одна из приятных вещей о LaTeX.
После многих лет мучений и нескольких неудачных попыток я собираюсь вернуться к этому, и я собираюсь попробовать Сфинкса. Он может генерировать HTML или LaTeX из реструктурированного текста.
Я надеюсь, что это будет гораздо более "легкий" вариант, чем полноценный DocBook, но со многими преимуществами.
Да, конвертеры LaTeX-HTML раньше сосали (вы, вероятно, пробовали LaTeX2HTML), но в последнее время они стали лучше. Tex4ht легко настраивается и производит хороший XHTML+CSS. Смотрите также другие конвертеры.
Вы также можете использовать Docbook, если вы можете писать в нем. Есть конвертеры из DocBook в HTML и LaTeX (или в PDF напрямую); Примером последнего является dblatex.
Смотрите этот пост: LaTeX vs Docbook.
Вы можете сделать шаг назад и использовать что-то вроде DocBook и рендерить в PDF через LaTeX и HTML прямо из файлов DocBook. Кроме того, Adobe Technical Communication Suite (Framemaker) позволит вам получить документ из одного источника в форматах PDF и HTML. Смотрите эту публикацию для краткого изложения по различным системам технической документации.
Это личный выбор, но в теории латекс идеален, но на практике это боль в заднице. Я использую VS.NET HTML редактор + необработанное редактирование HTML, когда мне это нужно.
Поэтому я считаю, что использование HTML-редактора WSIWYG - лучший выбор. Вы всегда можете использовать простой инструмент для преобразования его в PDF, и вы всегда можете редактировать HTML, когда вам нужно что-то продвинутое. Кроме того, его легче подключить к сети, когда это необходимо.
Вот так я управляю своими программными документами и прекрасно работает для меня.
Поскольку ответ, в котором упоминается Asciidoc, был несколько коротким на примерах, вот несколько вещей, которые вы ищете:
PlasTeX выглядит как хороший конвертер из латекса в HTML, хотя я сам не пробовал.
Мой друг Роб Фелти написал пост в блоге, рассказывая о его достоинствах: http://blog.robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter/
Читайте о формате EPUB. Его формат электронной книги. http://en.wikipedia.org/wiki/EPUB
У меня недостаточно очков, чтобы комментировать, но, чтобы поддержать ответ от пластекса, вот обновленная ссылка на пример пластекса:
http://robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter
Я использовал TeXinfo в прошлом, и он делает хорошую работу. Вот пример: http://yootles.com/api. Я бы предпочел придерживаться LaTeX, а не использовать другой язык.
Я не уверен, что латекс действительно лучший инструмент для этого. Проблема, с которой вы сталкиваетесь при использовании обычного конвертера из латекса в html, свидетельствует о проблеме: html просто не так выразителен, как латекс.
Если вы настаиваете на использовании латекса в html, позаботьтесь об использовании ограниченного подмножества, которое может быть разумно преобразовано.
Мы использовали WebWorks ePublisher (www.webworks.com), который предлагает как несколько форматов с одним источником (мы используем Word), так и возможность вывода во многие форматы вывода (мы выводим в Adobe PDF и онлайн-справку (.CHM),
Мы столкнулись с этой проблемой в академическом проекте, который включал программное обеспечение Eclipse, и мы использовали plastex для преобразования Latex в HTML и справку Eclipse. Заставить его работать было довольно сложно, но конечный результат выглядит действительно хорошо. Вы можете увидеть все три версии здесь:
Кроме того, поскольку это открытый проект, доступен код (сценарии сборки). У нас есть система непрерывной сборки (Jenkins), которая перестраивает все, когда регистрируется новый Latex. Это особенно приятно, поскольку разработчикам не нужно устанавливать набор инструментов в своих системах. Они просто проверяют новый Latex и проверяют на сервере, правильно ли был создан HTML. Источники:
http://sourceforge.net/p/rodin-b-sharp/svn/HEAD/tree/trunk/Handbook/org.rodinp.handbook.feature/
Лучший, Майкл
Если ничего не помогает, вы можете взять конвертер LaTeX в XML и написать простую таблицу стилей XSLT, чтобы преобразовать ее в HTML, или создать таблицу стилей CSS и напрямую прикрепить ее к файлу XML.
Латекс? Шутки в сторону? Я не знал, что кто-то за пределами академии все еще использовал это. Я бы пошел с HTML, который вы можете сохранить как PDF из веб-браузера. Если вам действительно нужны какие-то продвинутые типографские материалы, используйте вместо этого Word - у него есть способ сохранить в HTML (возможно, не так чисто, как хотелось бы), и вы можете сохранить как PDF с помощью бесплатного плагина (загружается отдельно),
О, и я бы не стал использовать такие вещи, как InDesign - они излишни. Кроме того, не стоит платить за Acrobat Professional - существует миллион бесплатных решений.