То есть про markdown ты не в курсе, или он сразу отпадает про причине своей простоты? Куча проектов на том же гитхабе использует этот формат для документации и вики (есть в том числе сложные иерархические руководства с перекрёстными ссылками и генерацией оглавления/references).

Про конвертацию HTML, PDF можно не думать, пока есть такие инструменты как pandoc (конвертация с любого формата в любой). Есть куча генераторов markdown -> HTML -> что угодно.

То есть про markdown ты не в курсе, или он сразу отпадает про причине своей простоты?

Слышал, не пользовался, на ум не пришло. А что поверх него для структурированных документов? Вроде таких:

<req name="check_password" status="ok">
    Программа должна проверять пароль на сложность 
    <test_case>Задать пароль из 5 символов</testcase>
    <test_case>Задать пароль в одном регистре</testcase>
    ...
</req>

Куча проектов на том же гитхабе использует этот формат для документации и вики (есть в том числе сложные иерархические руководства с перекрёстными ссылками и генерацией оглавления/references).

Ссылкой на какой-нибудь не поделитесь?

Про конвертацию HTML, PDF можно не думать, пока есть такие инструменты как pandoc (конвертация с любого формата в любой).

Фантастика какая-то.

проектную, описывающую архитектуру, требования, тестовые планы, и пользовательскую

вы будете смеятся, НО, это форматы ms-word и OO :-) может кроме тестовых планов может быть.

Ого, давно интересует тот же вопрос. Подписался.

А что поверх него для структурированных документов?

Наблюдаю эпидемию XMLя неокортекса. Документация - для читателя, а он при любой обработке прочтёт что-то типа:

= Требования

== сложность пароля

программа должна ...

=== тесты

1. задать ...
2. задать ...

т.ч. более навороченная структура не нужна.

почему odf - не вариант? У него есть свой diff, а с помощью некоторой утилитки (odt2txt, кажется) можно прикрутить его к СКВ. Помнится, я так делал (не для себя) и всё работало нормально

но html убогий

Ну так понятное дело: html не рассчитан на верстку текстов! Но на худой конец сойдет latex2html.

org-mode. Как раз plain text, удобная разметка, и, конечно же структурирование. Плюс куча поддерживаемый форматов для экспорта.

Я рекомендую sphinx (http://sphinx-doc.org/).

Простой но фичастый текстовый формат.

Есть поддержка структурированной разметки + расширения своими директивами.

Нормальная поддержка ссылок.

Нормальный вывод в html, приемлемый в pdf.

ReST

т.ч. более навороченная структура не нужна.

А что делат, когда требований будет 100 или 1000 и захочется вывести только те (10 штук), что не реализованны?

Я, конечно, догадываюсь, что это не имеет отношения к representational state transfer, но что-то ничего другого не гуглится.

Ссылочку бы.

почему odf - не вариант?

1) odf - никак не структурированная разметка.

2) съезжающие стили, много ручного форматирования

У него есть свой diff, а с помощью некоторой утилитки (odt2txt, кажется) можно прикрутить его к СКВ.

diff есть, а вот merge - нет.

Ссылочку бы.

http://docutils.sourceforge.net/rst.html он же используется в http://sphinx-doc.org/

почему odf - не вариант? У него есть свой diff, а с помощью некоторой утилитки (odt2txt, кажется) можно прикрутить его к СКВ. Помнится, я так делал (не для себя) и всё работало нормально

google подсказал ссылку, но все равно что-то не то. Нету там удобного языка разметки :)

Я рекомендую sphinx (http://sphinx-doc.org/)

Хороший вариант. Чуть позже посмотрю подробно.

Спасибо.

ReST

есть какие-то объективные причины для предпочтения reST, например markdown'у? или просто потому что питон?

есть какие-то объективные причины для предпочтения reST, например markdown'у?

Наличие таки-спецификации, которой нет у md. Есть десяток разных диалектов md.

Расширяемость reST собственными директивами.

А это точно задача документации?

А это точно задача документации?

А что, есть толковые свободные системы управления требованиями? А с какого масштаба ими нужно начитать пользоваться?

есть какие-то объективные причины для предпочтения reST, например markdown'у?

У меня - нет. Просто это первый из текстовых языков разметки, который мне попался на глаза.

restructured text, markdown, textile - чо хошь

Судя по описанию тебе нужно что-то типа ланчпада. А это совсем-совсем далеко от документации.

есть толковые свободные системы управления требованиями? А с какого масштаба ими нужно начитать пользоваться?

Для масштаба есть bugzilla, launchpad

А для списка задач мне и issue в github'е хватает.

Судя по описанию тебе нужно что-то типа ланчпада. А это совсем-совсем далеко от документации.

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

RedHat и Fedora пишут большие доки в publican:

https://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/

Внутри там Docbook, а снаружи обертка для кастомных тем, упрощенного структурирования, публикации на веб-сервер и т.п.

Нету там удобного языка разметки :)

а, сорри, про этот пункт не углядел...

asciidoc + noweb

Буду оригинален: texinfo

те (10 штук), что не реализованны

В режиме бровзинга: /TODO<CR> потом n...

В batch, например:

#!/bin/sed -rf
1,/^= +Требования/ d
1,/^== +/ { h ; d ; }
/^= +/,$ d
H
$ g
/^== +/ ! d
/^== +/ {
x
s/\n== +.*$//
/TODO/ ! d
}

doxygen — синхронизация с кодом, приемлемый html. Хорош для описания кода, но инструкции, примеры и пр. писать замучаешься. Пригоден для малых и средних проектов.

texinfo — почти как ТеХ, но ориентирован на описание кода. Удобен для всего кроме формул (они есть, но ... тяжко). Хорошо структурирован для большой документации с примерами, рисунками, выделением цветом или начертанием, и т.д. и т.п. Отлично экспортирует в html, info и еще кучу форматов. Хорошо в pdf, но в pdf нет поддержки русского языка (точнее мне не удалось ее настроить).

http://mwolson.org/projects/EmacsMuse.html