Может ли LaTeX использоваться для создания любой документации, которая прилагается к программному обеспечению?

Ответ 1

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

Самое лучшее в LaTeX - это то, что вы занимаетесь контентом и структурой, а не только визуальным макетом. Это похоже на написание HTML с CSS, а не с чистого HTML.

Вот несколько причин, по которым я думаю, что LaTeX полезен для создания некоторой документации:

Одна из причин заключается в том, что работа с несколькими стилями более структурирована, а стили более "логичны", чем "визуальные". Например, если вы печатаете Word, каждый раз, когда вы хотите указать класс или объект, вы меняете стиль. В LateX, когда я печатаю, я пишу что-то вроде:

bla bla bla ~\methodName {foo} bla л ~\{имя класс FooBar}.

Я нахожу, что для длинных документов это полезно. Я легко могу найти имена классов, изменить их и т.д.

Вторым преимуществом является то, что я могу использовать макросы для объектов. Например, предположим, что у меня есть модуль, который обрабатывает некоторые функции, но его имя может измениться позже или что я не уверен, что это такое. У меня может быть макрос, называемый \ModuleForXXX, и когда я в конечном итоге выбираю имя или меняю его.

Третье и, возможно, самое важное преимущество заключается в том, что проще создать документ из иерархии файлов в LaTeX, чем в документе Word. Обычно у меня есть основной файл, который затем включает в себя другие файлы, которые затем включают другие файлы и так далее. Я рассматриваю его иерархически (по крайней мере, в Windows с WinEDT), и я могу легко изменить порядок вещей, просто изменив включения. Излишне говорить, что я также использую для фактического содержания фрагментов кода и текста документации.

LaTeX имеет несколько недостатков: 1) Мало кто знает это, и некоторые люди, которые привыкли к Word, просто возмущаются им. Однако для тех, кто читает окончательный PDF, это не имеет значения. 2) Размещение изображений может быть немного сложным, хотя вы можете переопределить параметры и заставить LaTeX слушать ваши инструкции. 3) Он лучше всего работает с конфигурацией с двумя мониторами.

Ответ 2

Многие проекты в экосистеме Python теперь используют Sphinx для создания своей документации. LaTeX является одним из многих выходных форматов, которые Sphinx может производить. Я считаю, что Doxygen, механизм документации С++/C/Python/ Objective-C/.. также может выводить результат LaTeX.

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

Ответ 3

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

Самая большая проблема с LaTeX, по крайней мере, с TeXShop на Mac, - это форматирование и размещение изображений. Инструменты в MS Office или OpenOffice гораздо полезнее для этого. Возможность изменять шрифт хороша только при публикации в разных журналах; согласованный дизайн документации может быть легко обработан шаблонами и т.п. в офисном программном обеспечении.

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

Ответ 4

Существует система Knuth CWEB, которая использует TeX. http://www-cs-faculty.stanford.edu/~knuth/cweb.html

Ответ 5

Я использовал его для документации по программному обеспечению, и для этого он работает очень хорошо. Одним из ключевых преимуществ является возможность интеграции документации из нескольких источников. Вы можете (например) визуализировать ссылку API или словарь данных в LaTeX и перекрестно ссылаться на другие части спецификации. Если вы можете поместить фрагменты LaTeX в комментарии API, XREF могут даже идти в обоих направлениях.

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

Ответ 6

Большое программное обеспечение с открытым исходным кодом создает свою документацию с нуля. Система документации Perl (POD, man-like documentation) поддерживает экспорт в LaTeX, который я иногда использовал для его печати. ​​

Ответ 7

GNU Troff (Groff), по-видимому, более популярен, чем LaTeX в сообществе разработчиков программного обеспечения. Согласно Wikipedia, O'Reilly также использует его для своих книг.

Ответ 8

Инструмент для определения сегментации и регистрации Insight (www.itk.org) имеет очень классную систему, в которой источник LaTeX помещается в комментарии исходного кода и они на самом деле genereate несколько хрустали руководство по программированию страниц из него.

Ответ 9

Я помог настроить LaTeX для целей документации в бывшей компании. Он работал, но технические писатели не любили его.

Основная жалоба заключалась в том, что они считали, что это рабство. Что было хорошо, они не могли слишком многое переваривать.

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

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

Ответ 10

Я использовал это иногда, но мой босс больше в офисных документах, и если он пишет документацию или ее части, мы не используем LaTeX.

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

Ответ 11

Я не использовал LaTeX, так как я перестал быть инженером-механиком. Я знаю, что он широко используется для набора документов с математикой. Любой, кто подает документ для рассмотрения журналом ASME, обязательно его использует. Я использовал его, чтобы набирать свою диссертацию и любил ее.

Но с тех пор я не видел ничего, кроме Word, без какого-либо исключения.

Ответ 12

Я просто обнаруживаю, какая боль для создания полноразмерных символов circumflex (^) и тильды (~) в LaTeX. Какие из них удобны для набора исходного кода на таких языках, как C.

Здесь - описание искажений, видимо необходимых для тильды; Я просто задал аналогичный вопрос на этой доске об обводнении.