| Версия для печати темы
Нажмите сюда для просмотра этой темы в оригинальном формате |
| Форум программистов > wiki.vingrad.ru > Документация в вики |
| Автор: Любитель 23.9.2006, 20:28 | ||
| При написании документации достаточно часто описывается некоторый элемент (класс, структура, модуль, пространство имён, пакет и т. д.) и его подэлементы. При этом в нормальной документации очень часто делают так: 1. Вначале пишется структура этого элемента с подразделами (вроде паблик, прайват и т. д.) локальными (в пределах страницы) ссылками на подробное описание. 2. Затем идёт более подробное описание элемента. 3. После подэлементы с более подробным их описанием. При этом при описании подэлементов есть стандартные разделы. Вроде возвращаемого значения, списка аргументов, исключений, предусловий и т. д. Наиболее естественным методом написания документация в подобном стиле будет использование подразделов, но отображаться это будет совсем не так как хочется. Хотелось бы что-то типа такого:
Это, кончено, тупой пример, да и синтаксис оставляет желать лучшего. Но я думаю общими усилиями можно придумать нечто удобное и всех многих устраивающее. Кроме того хорошо бы иметь специальный синтаксис для ссылок внутри документации на документируемые элементы (например, MyError). Ещё раз подчёркиваю, что этот пример выражает лишь суть идеи, а не заказ на определённый синтаксис. В общем придётся поработать (и над утверждением синтаксиса), и над расширением, но результат по-моему того стоит. В противном случае (если не найдётся тех, кто поддержит мою идею) надо хотя бы создать (и потом опубликовать) какие-то единые правила. |
| Автор: Cheba 23.9.2006, 20:59 |
| В чем суть идеи? Я не понял. Если дело касается структуры и оформления документа, то это все можно сделать с помощью wiki-синтаксиса. |
| Автор: Любитель 23.9.2006, 21:05 |
| Возможно, конечно я плохо знаю разметку. Тогда вопрос - как сделать лоакльную ссылку не на подраздел. К примеру: http://doc.trolltech.com/4.1/qcombobox.html (пример документации). И второе (собственно суть идеи) - сделать дополнительный синтаксис, позволяющий автоматом оформлять это в едином стиле. Либо просто официально опубликовать некоторый единый стиль доков. |
| Автор: Cheba 23.9.2006, 21:30 |
| Если ты присмотришься, то там ссылки тоже указывают на заголовки. В вики каждый заголовок создает раздел. У каждого раздела есть своя ссылка. Посмотреть ее можно в содержании статьи. О создании ссылок почитай хелп. Например, вот http://ru.wikipedia.org/wiki/%D0%92%D0%B8%D0%BA%D0%B8%D0%BF%D0%B5%D0%B4%D0%B8%D1%8F:%D0%9A%D0%B0%D0%BA_%D0%BF%D1%80%D0%B0%D0%B2%D0%B8%D1%82%D1%8C_%D1%81%D1%82%D0%B0%D1%82%D1%8C%D0%B8#.D0.A1.D1.81.D1.8B.D0.BB.D0.BA.D0.B8.2C_URL. |
| Автор: Exception 23.9.2006, 22:11 |
| Ссылки на отдельные заголовки делаются так: [[Название страницы#Заголовок]]. Насчёт единого стиля - можно было бы сделать шаблон, но тут несколько не то, боюсь, придётся делать расширения.. Гемор. |
| Автор: Cheba 23.9.2006, 23:58 |
| Какие расширения? Я до сих пор не понимаю о чемь речь... |
| Автор: Cr@$h 24.9.2006, 01:05 |
| Да ну. Я сам с трудом понимаю. Не стоит накладывать такие жёсткие рамки. Оформляй все стаьи в едином стиле и всё. К тому же не все статьи будут описывать какой-то класс. Главное выработать у себя дисциплину и следовать ей. Основные рекомендации даны в руководствах Viki. |
| Автор: Любитель 24.9.2006, 20:06 | ||
Енто я, к счастью, понял. Вопрос в другом - ссылка на раздел, так скажем без заголовка. Можно по другому - невидимый заголовок. Иначе говоря, обычные якоря (закладки). |
| Автор: Cr@$h 24.9.2006, 21:56 | ||||||
Понимаю по отдельности, но не вижу связи между ними. Поясни, пожалуйста. |
| Автор: Любитель 25.9.2006, 15:57 |
| Всё это означает - заголовок есть в структуре (для адресации), но нет при отображении страницы. Единый стиль в моём понятии включает: 1. Именование секций. Кто-то напишет "Список исключений", кто-то - "Исключения", кто-то "Throws" и т. д. 2. Оформление секций. Кто-то напишет их жирными, кто-то другим цветом и т. д. Кто-то оформит заголовок секции отдельным параграфом или элементом списка, кто-то - нет и т. д. |
| Автор: Cr@$h 25.9.2006, 18:00 | ||||
Если заголовок в коде вики создан как =...= Заголовок =...=, то в содержании он будет присутствовать и он может якорем выступать.
его хорошо бы просто поддерживать один и тот же. Если пришёл новичок, написал что-то и ушёл, то обычно смотритель за разделом должен подвести статью под общий стиль. Есть рекомендации по оформлению статьей, но тонкости, про которые ты говоришь, по-моему, нигде не оговорены. Лучше выработать хороший стиль и применять его на всех страницах. |
| Автор: Любитель 2.10.2006, 15:15 | ||
а как сделать, чтобы он не пристутствовал в содержании, т. е. использовался только для ссылки ? |
| Автор: Cr@$h 2.10.2006, 16:42 | ||
Как тебе сказать.. я не знаю, если честно. Ведь сам посуди:
|
| Автор: Cheba 3.10.2006, 11:09 |
Хитрости не знаю. Практической пользы не вижу.  |
| Автор: Cr@$h 3.10.2006, 16:11 |
| Можешь ещё просто содержание отключить: __NOTOC__ Но это рекомендуется делать только на заглавных страницах. |
| Автор: Любитель 5.10.2006, 09:43 |
| Нашёл кое-что интересное, связанное с моими идеями: http://boost.org/tools/quickbook/doc/html/quickbook/syntax.html. По крайней мере синтаксис можно посмотреть. Добавлено @ 09:45 Ещё - обязательно надо добавить подсветку синтаксиса  |
| Автор: Cheba 5.10.2006, 18:01 |
| Там приведен расширенный синтаксис Textyle. Он несколько отличается от вики-разметки. Чего тебе не хватает из того, что есть там? Подсветка синтаксиса есть в ToDo-листе. К сожалению, сейчас у меня недостаточно времени, чтобы заняться ею. |
| Автор: Любитель 10.10.2006, 17:07 |
| Название беру с этой страницы: 1. Source Mode (подсветка с указанием языка, удобная) 2. Anchors и Anchor links (якоря) 3. function, class, member, enum or header links То, что я хочу  4. Макросы (def) - супер. |
| Автор: Cheba 15.10.2006, 15:56 |
| 1) Над этим ведутся работы. Немного. 2) У нас практически так же. Читаем http://meta.wikimedia.org/wiki/Help:Anchors и не стесняемся говорить с Гуглем. 3) Это все специфические для языка фишки. Если очень хочется - напиши шаблоны. (см. совет в предыдущем пункте  ).4) Не имеет практической ценности. |
| Автор: Любитель 15.10.2006, 22:45 | ||||||
Мдя туплю.
А где про это можно почитать (желательно на русском). Извеняюсь за нсатойчивость, просто времени искать реально нету (есть сейчас важные проблемы).
почему??? |
