Тема создана для обсуждения или публикации возможных способов создания программной документации с помощью программного инструментария доступного для ZX-Spectrum. Речь может идти, в том числе и о кросс-платформенных решениях.
Вид для печати
Тема создана для обсуждения или публикации возможных способов создания программной документации с помощью программного инструментария доступного для ZX-Spectrum. Речь может идти, в том числе и о кросс-платформенных решениях.
1. Документация, внедрённая в программный текст.
В сообщении рассматриваются возможные варианты включения
программной документации в текст программ на языке C и ассемблера, рассматриваются способы извлечения текста внедрённой в исходный текст программы документации в отдельный файл
и даются рекомендации по оформлению файлов документации.
К читателям форума: дополняйте, критикуйте, изменяйте.
Только, пожалуйста, НАУЧИТЕСЬ НОРМАЛЬНО ЦИТИРОВАТЬ,
ибо я примерно половину ваших писем вообще не понимаю
о чём речь. Приводите цитату полностью и давайте ссылку на оригинальное сообщение.
1.1. Использование препроцессора языка C.
При использовании в процессе сборки исходного кода препроцессора языка C, препроцессор может быть также
использован для извлечения внёдрённой в программный текст
документации. Это можно показать на простом примере:
Как видно, в случае если макрос DOC_MODE не определён на выходе препроцессора будет получена программа на языке C. В случае, если же макрос DOC_MODE определён будет выдан текст программной документации. Очевидно, что такой метод может работать не только с программами на языке C, а с любыми другими.Код:#ifdef DOC_MODE
Текст описания программы...
#else
void main() {
puts("hello world!");
}
#endif
К ним лишь, перед трансляцией, нужно применить C-препроцессор.
Однако, в таком случае может возникнуть специфическая проблема:
при выдаче ошибок компиляции или отладочной информации, номера
строк не будут соответствовать действительным в оригинальном исходном файле (с внедрённой документацией). В случае если компилятор или ассемблер ориентирован на совместную работу с C-препроцессором и воспринимает его директивы (вида
"# <номер строки>"), указывающие действительные номера строк,
это проблем не вызывает. Так, например компилятор языка C и
ассемблер фирмы HiTech позволяют использовать такой способ
документирования программ.
1.2. Использования средств ассемблера.
При использовании ассемблеров для ZX-Spectrum возможен
и другой вариант, в котором текст документации "компилируется"
как программа. Программа опять с помощью директив условной
компиляции разделяется на две части: документацию и текст программы. Документация описывается выражениями ассемблера
вида DB "текст". Для более удобной записи будет удобно использование макро-ассемблера, такого, например, как ALASM,
или другого, позволяющего передавать аргументами макроса
строковые выражения. Пример:
В ассемблере ZXASM, не поддерживающем передачу строковыхКод:
doc macro
ifdef DOC_MODE
db $1
db #0d
endif
endm
org #6000
doc "функция printchar..."
doc "выводит символ из регистра A"
main:
rst #10
ret
аргументов макросам, показанный пример можно переписать
следующим образом:
При компиляции приведённых примеров с неопределённой меткой DOC_MODE будет скомпилирована сама программа. При определении метки DOC_MODE в памяти будет сформирован текст документации. Осталось только его записать на диск как текстовый файл.Код:
org #6000
ifdef DOC_MODE
db "функция main..."
db "выводит символ из регистра A"
else
main:
rst #10
ret
endif
2. Компоновка документации.
Программная документация может состоять из частных описаний
различных функций, переменных, классов... наконец целых программных модулей, библиотек. Изначально, при использовании
одной из описанных выше техник извлечения внедрённого текста
документации из текста программы, текст сгруппирован в рамках
одного или нескольких файлов и размещён в той же
последовательности, как и в файлах исходных текстов программ.
Поэтому размещать текст программы в файлах желательно в том
порядке, в каком части документации должны содержаться в
результирующем файле документации.
При использовании препроцессора языка C для извлечения документации, текст документации извлекаемый из отдельных файлов
может компоноваться произвольно. При использовании ассемблера,
например ALASM, текст формируется строго в том порядке, в каком
его обрабатывает ассемблер. По этой причине и на уровне файла,
и на уровне программного модуля (библиотека, программа...) размещение текста программного кода желательно вести в той последовательности, в какой должна компоноваться документация
относящаяся к соответствующей части программного текста.
3. Подготовка текста к публикации
3.1. Оформление текста для ZX-Spectrum.
При создании файлов документации исключительнон в рамках платформы ZX-Spectrum созданием текстовых файлов, наверное,
следует и ограничиться. Просмотр файлов со специальной разметкой
во встроенном редакторе ассемблера затруднён. Как вариант, можно
предусмотреть всё же внедрение специальной разметки текста, например, для просмотра в редакторе ACEdit, или для принтера, а
также программу преобразования файла размеченного текст в файл
неразмеченного текста, пригодного к просмотру во встроенных редакторах различных ассемблеров.
Во всех случаях желательно предусмотреть некую минимальную
логическую разметку текста позволяющую более эффективно использовать функцию поиска подстроки в различных средсвах
просмотра текста.
В случае необходимости включения иллюстраций желательно
отобразить их средствами ASCII-графики -- это гарантирует
возможность просмотра иллюстраций в любых условиях.
3.2. Оформление текста в рамках платформы PC.
При использовании кросс-платформенных средств разработки
(в основном, на платформе PC), доступны более широкие возможности для обработки текста. Удобным способом подготовки
технической документации являются такие средства подготовки
текста как LaTeX и Docbook. Первый ориентирован скорей на
печатную версию документа (бумажную), но обладает широкими
возможностями оформления, внедрения рисунков и т.п. Второй,
говоря Docbook, подразумевается docbook-xml, ориентирован больше
на электронное web-представление и обладает несколько меньшими
возможностями. В любом случае и LaTeX (с помощью программ pdflatex, latex2html) и Docbook (xsltproc или другой xslt-процессор, а также FOP) позволяют получить на выходе качественные (в смысле форматирования) документы в pdf-файле или в html, снабжённые иллюстрациями, а также, что несомненно важно, гиперссылками.
Автор давно опробовал технологию Docbook и она дала хороший
результат.
Хочу высказаться не по содержанию документации, а по её форме. Я за то, чтобы создавать и использовать документацию в формате HTML и на Спектруме, и на ПЦ, то есть иметь единый формат. В подобной документации используется минимум тэгов, поэтому создать соответсвующий вьювер, который будет поддерживать этот минимум совсем не сложно! (Кстати, почему бы не создать такой вьювер в рамках ZX SDK?) За то выгода на лицо! Такую документацию можно будет одинаково легко смотреть и на Спектруме, и на ПЦ под разными ОС, а при необходимости и качественно распечатать.
По поводу внедрения документации в текст программы всем смотреть JavaDOC и из нёё вытекающие (PHPDOC, Summary в .NET).
Смысл сводится к тому, что есть некие "тэги" между которыми идёт текст документации, а затем специальная софтина обрабатывает текст программы на предмет генерации доки.
например:
; /// [DOC]
; /// PRINTCHAR - выводит в поток символ
; /// из регистра A
PRINTCHAR
RST #10
RET
почти каждый спековский ассемблер поддерживает экспорт в текст. а текст обработать- нефиг делать.
если грамотно настроить генерилку, то можно не ограничиваться ассемблером
// /// [DOC]
// /// example
void example(void) {}
/*
/// [DOC]
/// example2
*/
void example2(void) {}
1) не надо изголяться с DOC_MODE
2) документация не оторвана от текста программы (т.е. можно написать аффигительную генерилку, которая кроме выдирания доки, будет ещё раскрашивать и форматировать текст программы
Во-первых -- имеется ли конечная форма представления, подготовленный к публикации вариант, или форма используемаяЦитата:
Сообщение от CityAceE
при наборе текста? Они могут различаться.
Я могу сказать, HTML для изначального ввода любых текстов
пишущихся человеком практически непригоден. Только как
конечная форма предствления HTML представляет интерес, по
очевидным причинам (практически везде можно просмотреть
и распечатать, более-менее легко преобразовать в другую форму).
Почему HTML непригоден: он не позволяет как-то чётко структурировать текст на более глобальном уровне нежели разделение на такие элементы как заголовки, параграфы, спискиЦитата:
В подобной документации используется минимум тэгов, поэтому создать соответсвующий вьювер, который будет поддерживать этот минимум совсем не сложно!
и т.п. Это в свою очередь лишает возможности нумерации разделов
текста, возможности реализации гиперссылок на конкретный элемент
текста (именно так, как бы абсурдно не звучало -- HTML не позволит,
например, сослаться на раздел 1.2 или раздел с таким-то именем,
только на конкретную точку в тексте), сложно реализовать сноски,
плавающие комментарии и другие элементы. Плюс трудности с набором формул (MathML поддерживается далеко не везде...)
И трудности с получением качественных иллюстраций пригодных как для просмотра, так и для печати. Получить из HTML качественно отформатированный, пригодный для печати текст вообще практически невозможно. Единственный известный мне метод -- html2ps выдаёт текст разве что удовлетворительного качества
(в то время как LaTeX -- отличного). Распечатать же текст из типичного обозревателя, такого как IE или Mozilla без ухищрений
вообще практически невозможно: дойдёт до того, что даже рисунки
и таблицы будут рваться посередине страницы.
Я рассматриваю HTML исключительно как удобное средство для представления на экране, не более того.
А имеет ли смысл упираться в HTML? Фактически нужно:Цитата:
(Кстати, почему бы не создать такой вьювер в рамках ZX SDK?) За то выгода на лицо! Такую документацию можно будет одинаково легко смотреть и на Спектруме, и на ПЦ под разными ОС, а при необходимости и качественно распечатать.
* представление гипертекста (не обязательно HTML!);
* желательно иметь возможность представление элементов
текста непредставимого в plain-text файле, например,
дополнительные символы, верхние и нижние индексы,
разные шрифты и цвета -- я говорю желательно,
но не обязательно;
* желательно представление иллюстраций.
Попадались среди электронной прессы для ZX-Spectrum
экземпляры поддерживающие первый и третий пункт. И была
ещё в своё время, давно уже (~2000 год), программа, то ли frame maker, то ли paper maker -- для создания электронной "газеты"
для ZX-Spectrum. Программа спектрумовская, не писишная. Вот
её вьювер тоже неплох.
Другое дело, что подготовить такую документацию, без титанических усилий, исключительно на спектруме невозможно...
И ещё момент. Значительная часть документации просматривается
непосредственно в ходе написания кода. Это означает, что просматриваться она будет во встроенном реадакторе ассемблера.
Следовательно, он должен поддерживать такой "формат". Было бы
замечательно, если бы ALCO добавил в Alasm "двухоконность"
(когда экран по-вертикали делится на два окна), поддержку цветовых
кодов из ACEdit, поддержку гипер-ссылок и поддержку вставки
картинок. Скорей, это получится гибрид из ACEdit и ALASM. Было бы
здорово.
аласм поставляется не только для 8, но и для 7-пиксельных строк, куда поддержку цветов и картинок не вставишь. да и думаю большие проблемы с цветовыми кодами- текст-то токенизированный! комментарии тоже свой формат имеютЦитата:
Сообщение от fk0
зы. посмотри мою прогу QHTV. она изначально делалась для просмотра документации. есть все что надо и не надо. единственное серьезное ограничение вижу- размер текста. над этим буду работать.
2fk0> система самодокументировния вообще класс, только я не понял как там в детялах - смешивается код и сама прога (при генерировании), но это не самое важное.
Касательно редактирования/просмотра - действительно просто напросто делать комменты - через те же кривые чертЫ (символы "\") точки с запятой (";") ну и т.п. - в сам редктор будет иметь два сдвигаемых окна - одной поверх другого - когда программист движет курсором в соседнем окне автоматически подгружается (или просто выводится когда оно в памяти) коммент к указанной строчке текста асма. Причём при физической выгрузке на диске как раз будет текст состоять из строк ассемблера перемешанных со строчками помощи, а когда редактируется текст программы то для программиста это прозрачно - у него в соседнем окошке эти комменты.
При конечном существующем коде можно тоже без вопросов получить чистый код или чистый текст - опять же через парсер.
Идею поддерживаю, ставлю 5 баллов (-;
касательно конечной формы - внутри текста программы теги никакие не нужны - они просто будут мешать и давать повод очень "разумным" homo какую-нить дурь выдумлять. А во что преобразовать потом полученный от парсера док - это уже личное дело каждого.