InPlace: правильная CMS для разработчиков

Нуна попробовать

Спасибо, улыбнуло

wiki отменили? :)

>>Кто-нибудь пишет документацию к своим продуктам? Да

>>А на несколько HTML-страниц? Да

>>И выдерживает их в едином стиле оформления? Да

>>И затрачивает на это больше усилий, чем надо было бы? Нет

>>Посмотрите на InPlace, возможно, эта система решит большинство проблем. Убожество

Автор, открой для себя wiki (в том числе и оффлайновые)

Писать документацию на HTML? Ну уж дудки. Использую http://docutils.sourceforge.net/ и доволен.

В моём мнении - гнусная мерзость. XSLT, как и всё, связанное с XML - избыточно сложная и тяжёлая технология. Я умру писать пять килобайтов XSLT на два килобайта документации. Немедленно в топку.

Есть wiki. Есть ReST. Есть масса автоматических докгенераторов. Зачем ещё велосипеды, тем более такие монструозные?

> The raw data? I think the proofreader will not thank you. The HTML files? Then you have to repeat the proofreader's corrections in the source data.

Я представил себе корректора, который ручками правит HTML-код, и радостно рассмеялся.

> Автор, открой для себя wiki (в том числе и оффлайновые)

Начнём со сценария использования 1. Мы хотим проверить документацию на правильность. Что мы отошлём proofreadr'у?

> Писать документацию на HTML? Ну уж дудки. Использую http://docutils.sourceforge.net/ и доволен.

Аналогичный вопрос: мы хотим проверить документацию на правильность. Что мы отошлём proofreadr'у?

> В моём мнении - гнусная мерзость. XSLT, как и всё, связанное с XML - избыточно сложная и тяжёлая технология. Я умру писать пять килобайтов XSLT на два килобайта документации. Немедленно в топку.

В вашем мнении действительно гнусная мерзость. Впрочем, мнение автора новости тоже не лучше. Пока нормального и подходящего для всех средства документирования ещё не существует. Где-то удобен docbook, где-то TeX, а где-то wiki (но сильно затюненная).

> XSLT, как и всё, связанное с XML - избыточно сложная и тяжёлая технология

К сожалению, лучше XSLT пока ещё ничего не придумали.

> Есть wiki. Есть ReST. Есть масса автоматических докгенераторов. Зачем ещё велосипеды, тем более такие монструозные?

InPlace -- это не докгенератор. Это всовыватель шаблонов в доки. Разница большая.

Кстати о вики. Как вы в ней пишете документацию?

> Аналогичный вопрос: мы хотим проверить документацию на правильность. Что мы отошлём proofreadr'у?

В случае docutils отошлём reStructuredText. Он изначально задумывался так, чтоб его и без перегонки в HTML мог прочитать полный ламер.

> Что мы отошлём proofreadr'у?

Аналогичный вопрос: А что мы отошлем proofreader'у в случае использования InPlace. Ответ на него мы отошлем и в случае Wiki, DocBook, POD, Haddock, [C]WEB/[La]TeX и других форматов.

> К сожалению, лучше XSLT пока ещё ничего не придумали.

А с такими заявлениями даже спорить не хочется. Хочется попеременно то плакать, то смеяться.

deplate.sf.net txt2tags.sf.net ...

>> Автор, открой для себя wiki (в том числе и оффлайновые)

> Начнём со сценария использования 1. Мы хотим проверить документацию на правильность. Что мы отошлём proofreadr'у?

Про вики. Они как раз и придуманы для совместной работы над текстом. Корректор заходит на вики по ссылке, которую мы ему отошлём, и исправит всё, что надо. И даже если вика оффлановая, с вики-разметкой не разберётся только убогий. Тем более, что от корректора требуется только исправить мелкие ошибки в тексте, а крупные изменения должен делать сам автор по его замечаниям.

>> А с такими заявлениями даже спорить не хочется. Хочется попеременно то плакать, то смеяться.

Эту фразу надо запомнить, очень точно описывает впечатления от этой новости :-))

> Хочется попеременно то плакать, то смеяться.

Эмо на ЛОРе =8O

> В моём мнении - гнусная мерзость. XSLT, как и всё, связанное с XML

Согласен 100%. Здесь надо отличать то, для чего вы делаете текст. Если это тех. доки, они прекрасно обойдутся пятью тегами - "картинка", "жирный", "таблица", "список" и "заголовок". Сюда подойдёт ЛЮБАЯ самопальная технология, в т.ч. убогая wiki. Если это вёрстка для сайта или того хуже - для книги, я лучше ВСЁ сделаю в PDF - там тоже есть формы, ссылки, только выглядит это ВЕЗДЕ одинаково. Ну а всякие перделки типа сильверлайт или Веб-2 пусть развлекают тупых манагеров.

> Про вики. Они как раз и придуманы для совместной работы над текстом. Корректор заходит на вики по ссылке, которую мы ему отошлём, и исправит всё, что надо.

Немного добавлю. К вики довольно легко прикрутить средства трансляции wiki-кода в любой формат (html, chm итп). Правда, для этого нужна продуманная система wiki templates, категорий и прочего. Готового решения я пока нигде не видел, но думаю, что оно где-то существует. Работать с wiki-текстом ну просто фантастически удобно, но лишь при условии, что разработаны строгие правила его оформления.

doxygen + docutils + txt2man + wiki

что еще надо разработчику вообще и OSS в частности?

Ну не катит wiki ни фига.

Если у меня дока-сайт на три страницы, и писать текст я буду один, зачем мне весь этот геморрой с заведением wiki?

Ну ладно, допустим, что есть вика и в ней дока. Как я эту доку интегрирую в сайт?

Аналогично со всякими reStructuredText. Как я их html буду интегрировать в сайт?

А чем это лучше docbook'a или TeX'a?

> А чем это лучше docbook'a или TeX'a?

Другой принцип. Сходите по ссылке, помедитируйте над картинками и почитайте про use cases.

> Другой принцип. Сходите по ссылке, помедитируйте над картинками и почитайте про use cases.

Ходил. Ничего интересного. "No need of the “generate HTML” step". за преимущество не считаю.

Автор, я тебя поддерживаю. Решение очень интересное.

Я сам использую XSLT для генерации сайта и блога (и фида), но без round-trip, а просто makefile'ом.

Быдлам не понять суть XSLT.

>>Быдлам не понять суть XSLT.
Особенно тем быдлам, которые суют его где ни попадя.

>Быдлам не понять суть XSLT.

Даешь замену TCP на XSLT!!!

>> >> doxygen + docutils + txt2man + wiki

>> Ну не катит wiki ни фига.

предыдущие три слова ты судя по всему пропустил...

texi2html/man2html/latex2html генерируют вполне пригодный код для интеграции

Или я не понимаю, что подразумевается под интеграцией?

я наверное дурак, но так и не понял в чем преимущества...

ЗЫ - да, у меня есть разной степени тяжести (XML/Java/СУБД/ООП/etc)-фобии :)

> Ну ладно, допустим, что есть вика и в ней дока. Как я эту доку интегрирую в сайт? > Как я их html буду интегрировать в сайт?

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

А писать доку непосредственно в виде конечного HTML как минимум глупо. Писать в XML неудобно, просто фантастически неудобно, здесь как раз рулит вики.

>> Быдлам не понять суть XSLT. > Особенно тем быдлам, которые суют его где ни попадя.

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

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

WYSIWYG развратил население, и результат мы наблюдаем прямо тут, на ЛОРе.

>> texi2html/man2html/latex2html генерируют вполне пригодный код для интеграции >> >> Или я не понимаю, что подразумевается под интеграцией?

Подразумевается, что мне остаётся только сказать "scons sync" (ну или make) для выкладки результата на сайт. Это значит, что в полученном HTML должны быть header/footer как на всём сайте, ссылка на css, прописаны meta-заголовки keywords и description (кстати, откуда эти texi2html/man2html/latex2html их возьмут?) ну и так далее.

> дока пишется в каком-то формате, из которого потом автоматически генерится документ любого типа.

Это широко распространённое заблуждение среди тех, кто _не_ генерит документы хотя бы двух форматов -- html и pdf, -- и при этом следит за качеством результата. http://olpa.livejournal.com/55112.html

> А писать доку непосредственно в виде конечного HTML как минимум глупо.

Почему? В XML же пишут. Точно так же можно писать и в HTML.

> кстати, откуда эти texi2html/man2html/latex2html их возьмут?

Вестимо откуда, из шаблонов. А как с помощью данной cms в режиме single source генерировать документы, допустим html, pdf, rtf?

Давайте реальные примеры применения?
Я всегда пользовался wiki, perldoc, phpdoc, хватало и для мелких проектов и для огромных. Не вижу смысла что-то менять.
Кто пользовался этой CMS (ну надо же, так назвать)? Опишите, как вам удобно и приятно править xml, html, и делать сразу html, pdf, rss, rtf, doc, xls, man, jpg, и так далее документацию.

> Подразумевается, что мне остаётся только сказать "scons sync" (ну или make) для выкладки результата на сайт. Это значит, что в полученном HTML должны быть header/footer как на всём сайте, ссылка на css, прописаны meta-заголовки keywords и description (кстати, откуда эти texi2html/man2html/latex2html их возьмут?) ну и так далее.

Вы просто не осилили не один существущий инструмент. Когда мне понадобилось поместить на сайт документацию для питоновского проекта, я 10 минут приспособил к docutils и свои шаблоны, и CSS, и всё остальное (идею спёр у http://jinja.pocoo.org/). И ещё за 5 минут сделал выкладку результата на сайт одной командой с помощью rsync. Потом мне настолько это понравилось, что я весь сайт стал генерить из ReST. Результат, если интересно, тут: http://pybtex.sourceforge.net/.

Не нравится docutils — берём любую другую тулзу с любым другим человеческим языком разметки, их навалом. А писать всё это на HTML + XSLT я бы, наверно, повесился.

> Если у меня дока-сайт на три страницы

vim + text/html ?

> Результат, если интересно, тут: http://pybtex.sourceforge.net/

Я BiBTeX перегоняю в HTML так: bib2bib (с фильтрацией), bib2bbl (latex), bbl2html. Все скрипты - свои. PERL и bash.

Результат: http://www.pomorsu.ru/Departments/tphyslab/papers.html

>> > Подразумевается, что мне остаётся только сказать "scons sync" (ну или make) для выкладки результата на сайт. Это значит, что в полученном HTML должны быть header/footer как на всём сайте, ссылка на css, прописаны meta-заголовки keywords и description (кстати, откуда эти texi2html/man2html/latex2html их возьмут?) ну и так далее.

>> Вы просто не осилили не один существущий инструмент.

+1

Когда я слышу XML, у меня сразу возникают сомнения в компетентности того, кто собирается его использовать...

Конечно я понимаю, что XML ни в чем не виноват, виноваты "специалисты", которые выбирают инструменты согласно моде, а не потребностям...

> Аналогичный вопрос: мы хотим проверить документацию на правильность. Что мы отошлём proofreadr'у?

Ага, отошлите ему вики-форматированную статью сырцом.

Аффтар, походу стебёцца %-)

>Есть очень большая разница между "легко сделать" и "сделано, с документацией".

Вот та дохлая страничка с пятью кусками xslt - это документация???

> Самое главное: описаны сценарии использования (use cases). Они объясняют, почему остальные 99.99% CMS не подходят мне (и другим oss-разработчикам) ни капли.

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

> Тоже полезная штука: шаблоны решения простых задач на xslt. О, видимо под документациею имелась в виду другая страничка - та на которой юсадж и перечислены четыре опции командной строки команды inplace.py %-D

asciidoc über alles

> asciidoc über alles

а ещё рульно добывать огонь трением, да

> а ещё рульно добывать огонь трением, да

А что с ним не так?

http://www.methods.co.nz/asciidoc/

> You want to proofread the documentation. Which files will you give to a proofreader? > The raw data? I think the proofreader will not thank you.

В классической CMS пруфридеру даётся линк на статьи в админ. интерфейсе. А если ему не нравится и работа сильно ответственная или дорогая, то спросить чего ему надо, и это ему дать. Подразумевается, что скока оно бы не стоило, цена оправдывает результат. А стоить оно не может много. Дело пары минут набросать скрипт, выгнать текст из базы в любой согласованный формат, отдать на правку, получить результат, загнать обратно в базу.

И нефиг морочить людям голову и придумывать велосипеды на ровном месте.

> Вы просто не осилили не один существущий инструмент.

Всё верно, только второе "не" должно быть "ни". Почему не осилил? Потому что начального знакомства хватило для понимания, какие проблемы меня ждут впереди.

> Когда мне понадобилось поместить на сайт документацию для питоновского проекта, я 10 минут приспособил к docutils и свои шаблоны,

Тебе повезло уложиться в 10 минут. А меня не радует изучать 1001-й недоязык недошаблонов, чтобы понять, что лучше попробовать другую тулзу.

> Результат, если интересно, тут: http://pybtex.sourceforge.net/.

Ну хоть кто-то не теоретик, а практик. Это радует.

> В классической CMS пруфридеру даётся линк на статьи в админ. интерфейсе. А если ему не нравится и работа сильно ответственная или дорогая, то спросить чего ему надо, и это ему дать. Подразумевается, что скока оно бы не стоило, цена оправдывает результат. А стоить оно не может много. Дело пары минут набросать скрипт, выгнать текст из базы в любой согласованный формат, отдать на правку, получить результат, загнать обратно в базу.

Звучит красиво, но, увы, я не теоретик, а практик.

> И даже если вика оффлановая, с вики-разметкой не разберётся только убогий.

Ни в одной вике и ни в одном "удобном" текстонабивательном формате я не научился:

* делать meta-заголовки ketwords и description

* выставлять ширину столбцов у таблиц, и вертикальное выравнивание для ячеек таблицы

Кто меня научит? Или "мне это не надо"?

> Почему? В XML же пишут. Точно так же можно писать и в HTML.

мда... Вы не видите разницы между XML и HTML?

> * делать meta-заголовки ketwords и description

> * выставлять ширину столбцов у таблиц, и вертикальное выравнивание для ячеек таблицы

Учимся отделять логическое форматирование от физического. Вики — это метасреда, из которой делается нужное для работы окружение, пишутся трансляторы вики-кода в конкретный формат и т.п. Конкретных примеров привести не могу, так как вопросом этим не интересуюсь, но знаю по знакомым техдокам, что:

а) Уровень автоматизации там никакой б) Уровень технической грамотности техдоков никакой в) Программистов-техдоков фактически нет

Используемым софтом (например, AuthorIT) техдоки страшно недовольны, так как его возможности весьма ограничены, например, для коллективной работы. Такое ощущение, что создатели подобного софта банально боятся создать что-то требующего невизуального подхода.

Те идеи, которые я ранее в своих постах описывал, применяются по отдельности в разных продуктах, но ни в одном продукте все вместе не используются.