Описание языка
Документ предоставляет пользователю языка возможности для решения задач, которые описываются на формальном языке. Фактически документ создан для системных программистов, операторов ЭВМ, кодеров, верстальщиков и тестировщиков.
Стандарт для документа: ГОСТ 19.504-79.
В каких случаях необходим
Формальные языки включают в себя возможные языки программирования, разметки и описания структур, языки управления заданиями, языки описания экранных и печатных форм и т.д. Сами языки могу значительно отличаться друг от друга, но, при этом, все состоят из определенного набора элементов и подчиняются грамматическим правилам.
Основная задача описания предоставить пользователю полную информацию по формальному языку и дать возможность применять этот язык по своему усмотрению.
Содержание документа
Описание языка включает следующие пункты:
Назначение языка и его сфера применения.
Конечный результат, написанный на языке (программы, макросы и т.п.)
Синтаксические правила языка. Возможные элементы текста и варианты их взаимодействия.
Логика работы программы или обработки документа. Процесс может кординально отличаться. Например процессы компиляция и интерпретация программного кода.
Составные элементы языка и синтаксических конструкций. В основном это операторы, теги, ключи и т.д.
Встроенные функции (стандартные возможности).
Описании языка может содержать:
указания по применяемому стилю программирования;
виды ошибок, алгоритм их поиска и устранения;
рекомендации для оптимизации быстродействия или памяти;
список рекомендуемых трансляторов (фреймворков или парсеров).
И иные моменты взаимодействия с языком, которые помогут пользователю в работе с ним.
Методика и стиль изложения
Основная задача документа - донести до конечного пользователя основную идею языка. Сам текст должен быть понятным как для продвинутого программиста, так и для начинающего пользователя. Важно не углубляться в описание технологии программирования и не описывать подробно все базовые элементы (цикл, функции, константы и т.п.). Примеры допустимы, но только для того, чтобы показать синтаксис.
Структура документа
Согласно ГОСТ 19.506-79 структура описания языка программирования должна быть следующей:
Общие сведения.
Элементы языка.
Методы структурирования программы.
Средства обмена данными.
Встроенные элементы.
Средства отладки.