[doc] Оформление Wiki-страниц

[Даниил]

Думаю, целесообразнее к вопросу Си-интерфейса подойти позже, когда я займусь плагином DoxyWiki, там и решим. Что касаемо примеров кода, то тут, как мне кажется, логичнее сделать в виде одной страницы примеры для QBE, а примеры к Си-интерфейсу я слабо представляю себе какие можно привести. Единственное, что разумно было бы сделать -- разобрать шаблон решения для вторых и третьих задач (кроме последней), размещенных в ejudge, т.к. он отличается там только принтами. Но, опять же, это стоит уже делать после того, как разберемся с документацией к интерфейсу, ибо в разборе шаблона хорошо бы сделать перелинковку каждой используемой в нем структуры с соответствующей документацией.

С уважением,
Захаров Даниил

> 20 марта 2018 г., в 20:54, Хамикоев Александр <sanchese113 at yandex.ru> написал(а):
> 
> Добрый вечер,
> 
> Спасибо, что расписал все по пунктам, так не запутаемся. В принципе со всеми пунктами согласен.
> Кстати, думал уже насчет структуры и оформления разделов с документацией к Си-интерфейсу и примерами кода?
> 
> С уважением, Александр
> 
> 20.03.2018, 19:24, "Даниил Захаров" <mr.danz at yandex.ru>:
>> Добрый вечер.
>> 
>> В рамках требования использования рассылки для обсуждения рабочих моментов, предлагаю моему напарнику по Wiki, Александру, вынести на обсуждение тему оформления документации по каждому разделу.
>> 
>> Так как я уже начал заниматься своей частью (перевод документации), предлагаю для всех подобных статей и вещей использовать следующую структуру.
>> 
>> 1. Каждый текст разбивается на визуально удобно читабельные абзацы.
>>   1.1. Если у текста есть первоисточник, то под каждым таким абзацем указывать аналогичный абзац первоисточника.
>>     1.1.1. Думаю, теги <pre></pre> для выделения оригинала подойдут.
>>     1.1.2. Для каждой статьи обязательно указывать ресурс-первоисточник. Это можно сделать единоразово, в конце страницы: два отступа («\n») от конца текста, разделительная черта (<h1>, но лучше 4 тире - черта в Wiki-разметке), текст «Источник: », домен, к которому прилагается точная ссылка. Пример. Источник: [https://c9x.me/compile/doc/il.html#Types c9x.me].
>>   1.2. Разрешается создавать Wiki-структуры и использовать возможности HTML для оформления страниц.
>> 
>> 2. В каждой статье, в случае, если применяются аббревиатуры, либо термины, к каждому такому термину в русскоязычном тексте/переводе указывать ссылку на сторонний ресурс ([ссылка Термин]) или на уже существующую на нашей Wiki статью ([[Термин]] или, если термин склоняется, [[СтатьяНаWiki | Термин]]).
>> 
>> 3. Код оформляется двумя способами.
>>   3.1. Если строка используется в где-то в тексте, то её нужно выделить либо тегами <code></code>, либо <b></b> = <strong></strong>.
>>   3.2. Если код приводится после текста/абзаца, то каждая строка к каждой строке с кодом добавляем пробел в ее начало. Это выделит код в блок.
>>     3.2.1. Если в тексте есть указание на какой-то конкретный пример кода, который уже был приведен, либо только будет приведен, желательно, первую строку в п. 3.2. начать с <strong>Пример.<strong>.
>>     3.2.2. Если в тексте присутствует не один пример, а несколько, то каждый блок кода, являющийся примером, должен начинаться с <strong>Пример НомерПримера.</strong>.
>>   3.3. Комментарии в блоках кода для удобства чтения будем указывать по принципу QBE (у Python так же) - через символ решетки. То есть, например, %a = w add 0,1 # Кладем 1 в переменную а.
>> 
>> 4. В массивных текстах, в которых возможно логическое разделение на главы, лучше это практиковать. В Wiki-разметке первый уровень выделяется в два знака равно, второй в три знака равно, третий - в четыре, и тд. Пример: == Глава 1 ==, === Раздел 1 (первой главы) ===.
>> 
>> 5. В случае возникновения проблем с переводом, либо при отсутствии возможности однозначной трактовки, обязательно указывать через слэш, либо в круглых скобках вторую возможную трактовку/комментарий/примечание.
>> 
>> С уважением,
>> Захаров Даниил
>> _______________________________________________
>> doc mailing list
>> doc at compilers.ispras.ru
>> https://compilers.ispras.ru/cgi-bin/mailman/listinfo/doc