При написании документации достаточно часто описывается некоторый элемент (класс, структура, модуль, пространство имён, пакет и т. д.) и его подэлементы. При этом в нормальной документации очень часто делают так:
1. Вначале пишется структура этого элемента с подразделами (вроде паблик, прайват и т. д.) локальными (в пределах страницы) ссылками на подробное описание.
2. Затем идёт более подробное описание элемента.
3. После подэлементы с более подробным их описанием.
При этом при описании подэлементов есть стандартные разделы. Вроде возвращаемого значения, списка аргументов, исключений, предусловий и т. д.
Наиболее естественным методом написания документация в подобном стиле будет использование подразделов, но отображаться это будет совсем не так как хочется. Хотелось бы что-то типа такого:


Это, кончено, тупой пример, да и синтаксис оставляет желать лучшего. Но я думаю общими усилиями можно придумать нечто удобное и всех многих устраивающее.
Кроме того хорошо бы иметь специальный синтаксис для ссылок внутри документации на документируемые элементы (например, MyError). 

Ещё раз подчёркиваю, что этот пример выражает лишь суть идеи, а не заказ на определённый синтаксис. В общем придётся поработать (и над утверждением синтаксиса), и над расширением, но результат по-моему того стоит.

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

Это сообщение отредактировал(а) Любитель - 23.9.2006, 20:33

В чем суть идеи? Я не понял.

Если дело касается структуры и оформления документа, то это все можно сделать с помощью wiki-синтаксиса.

Возможно, конечно я плохо знаю разметку. Тогда вопрос - как сделать лоакльную ссылку не на подраздел. К примеру: здесь (пример документации).

И второе (собственно суть идеи) - сделать дополнительный синтаксис, позволяющий автоматом оформлять это в едином стиле. Либо просто официально опубликовать некоторый единый стиль доков.

Если ты присмотришься, то там ссылки тоже указывают на заголовки. В вики каждый заголовок создает раздел. У каждого раздела есть своя ссылка. Посмотреть ее можно в содержании статьи. О создании ссылок почитай хелп. Например, вот здесь.

Ссылки на отдельные заголовки делаются так: [[Название страницы#Заголовок]]. Насчёт единого стиля - можно было бы сделать шаблон, но тут несколько не то, боюсь, придётся делать расширения.. Гемор.

Какие расширения? Я до сих пор не понимаю о чемь речь...

Да ну. Я сам с трудом понимаю. Не стоит накладывать такие жёсткие рамки. Оформляй все стаьи в едином стиле и всё. К тому же не все статьи будут описывать какой-то класс. Главное выработать у себя дисциплину и следовать ей. Основные рекомендации даны в руководствах Viki.

Енто я, к счастью, понял. Вопрос в другом - ссылка на раздел, так скажем без заголовка. Можно по другому - невидимый заголовок. Иначе говоря, обычные якоря (закладки).

Понимаю по отдельности, но не вижу связи между ними. Поясни, пожалуйста.

Всё это означает - заголовок есть в структуре (для адресации), но нет при отображении страницы.
Единый стиль в моём понятии включает:
1. Именование секций. Кто-то напишет "Список исключений", кто-то - "Исключения", кто-то "Throws" и т. д.
2. Оформление секций. Кто-то напишет их жирными, кто-то другим цветом и т. д. Кто-то оформит заголовок секции отдельным параграфом или элементом списка, кто-то - нет и т. д.

Если заголовок в коде вики создан как =...= Заголовок =...=, то в содержании он будет присутствовать и он может якорем выступать.

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

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

Как тебе сказать.. я не знаю, если честно. Ведь сам посуди:

• Чтобы можно было указывать текст как якорь в ссылке на страницу, он д.б. заголовком любого уровня в статье.
• Чтобы текст не присутствовал в содержании, он не д.б. заголовком любого уровня на странице.

Взаимное исключение, как видишь. Может, Cheba знает хитрость с содержанем. Например, не включать в содержание заголовки такого-то уровня (=== === -- третьего).

Хитрости не знаю. Практической пользы не вижу. 

Можешь ещё просто содержание отключить: __NOTOC__
Но это рекомендуется делать только на заглавных страницах.