Важная информация

User Tag List

Показано с 1 по 8 из 8

Тема: Программная документация.

  1. #1
    Activist Аватар для fk0
    Регистрация
    18.02.2005
    Адрес
    St. Petersburg
    Сообщений
    415
    Благодарностей: 3
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    Post Программная документация.

    Тема создана для обсуждения или публикации возможных способов создания программной документации с помощью программного инструментария доступного для ZX-Spectrum. Речь может идти, в том числе и о кросс-платформенных решениях.
    Последний раз редактировалось fk0; 06.12.2005 в 13:18.

  2. #1
    С любовью к вам, Yandex.Direct
    Размещение рекламы на форуме способствует его дальнейшему развитию

  3. #2
    Activist Аватар для fk0
    Регистрация
    18.02.2005
    Адрес
    St. Petersburg
    Сообщений
    415
    Благодарностей: 3
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    По умолчанию Самодокументирующийся код.

    1. Документация, внедрённая в программный текст.

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

    К читателям форума: дополняйте, критикуйте, изменяйте.
    Только, пожалуйста, НАУЧИТЕСЬ НОРМАЛЬНО ЦИТИРОВАТЬ,
    ибо я примерно половину ваших писем вообще не понимаю
    о чём речь. Приводите цитату полностью и давайте ссылку на оригинальное сообщение.


    1.1. Использование препроцессора языка C.

    При использовании в процессе сборки исходного кода препроцессора языка C, препроцессор может быть также
    использован для извлечения внёдрённой в программный текст
    документации. Это можно показать на простом примере:

    Код:
    #ifdef DOC_MODE
    
       Текст описания программы...
    
    #else
    
    void main() {
            puts("hello world!");
    }
    
    #endif
    Как видно, в случае если макрос DOC_MODE не определён на выходе препроцессора будет получена программа на языке C. В случае, если же макрос DOC_MODE определён будет выдан текст программной документации. Очевидно, что такой метод может работать не только с программами на языке C, а с любыми другими.
    К ним лишь, перед трансляцией, нужно применить C-препроцессор.
    Однако, в таком случае может возникнуть специфическая проблема:
    при выдаче ошибок компиляции или отладочной информации, номера
    строк не будут соответствовать действительным в оригинальном исходном файле (с внедрённой документацией). В случае если компилятор или ассемблер ориентирован на совместную работу с C-препроцессором и воспринимает его директивы (вида
    "# <номер строки>"), указывающие действительные номера строк,
    это проблем не вызывает. Так, например компилятор языка C и
    ассемблер фирмы HiTech позволяют использовать такой способ
    документирования программ.


    1.2. Использования средств ассемблера.

    При использовании ассемблеров для ZX-Spectrum возможен
    и другой вариант, в котором текст документации "компилируется"
    как программа. Программа опять с помощью директив условной
    компиляции разделяется на две части: документацию и текст программы. Документация описывается выражениями ассемблера
    вида DB "текст". Для более удобной записи будет удобно использование макро-ассемблера, такого, например, как ALASM,
    или другого, позволяющего передавать аргументами макроса
    строковые выражения. Пример:
    Код:
    doc      macro
               ifdef DOC_MODE
                       db $1
                       db #0d
               endif
               endm
    
         org #6000
         
         doc "функция printchar..."
         doc "выводит символ из регистра A"
    main:
         rst #10
         ret
    В ассемблере ZXASM, не поддерживающем передачу строковых
    аргументов макросам, показанный пример можно переписать
    следующим образом:

    Код:
           org #6000
    
    ifdef DOC_MODE
          db "функция main..."
          db "выводит символ из регистра A"
    else
    main:
               rst #10
               ret
    endif
    При компиляции приведённых примеров с неопределённой меткой DOC_MODE будет скомпилирована сама программа. При определении метки DOC_MODE в памяти будет сформирован текст документации. Осталось только его записать на диск как текстовый файл.


    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 и она дала хороший
    результат.

  4. #3
    Administrator Аватар для CityAceE
    Регистрация
    13.01.2005
    Адрес
    г. Владивосток
    Сообщений
    3,088
    Благодарностей: 1344
    Записей в дневнике
    6
    Mentioned
    5 Post(s)
    Tagged
    0 Thread(s)

    По умолчанию

    Хочу высказаться не по содержанию документации, а по её форме. Я за то, чтобы создавать и использовать документацию в формате HTML и на Спектруме, и на ПЦ, то есть иметь единый формат. В подобной документации используется минимум тэгов, поэтому создать соответсвующий вьювер, который будет поддерживать этот минимум совсем не сложно! (Кстати, почему бы не создать такой вьювер в рамках ZX SDK?) За то выгода на лицо! Такую документацию можно будет одинаково легко смотреть и на Спектруме, и на ПЦ под разными ОС, а при необходимости и качественно распечатать.
    С уважением, Станислав.

  5. #4
    Veteran Аватар для Sinus
    Регистрация
    29.01.2005
    Адрес
    Belarus, Grodno
    Сообщений
    1,270
    Благодарностей: 190
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    По умолчанию

    По поводу внедрения документации в текст программы всем смотреть 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) документация не оторвана от текста программы (т.е. можно написать аффигительную генерилку, которая кроме выдирания доки, будет ещё раскрашивать и форматировать текст программы
    [target] [zemu] [js8x] [pouet 1, 2]
    KAY-1024, 5''FDD, 3''FDD, HDD

  6. #5
    Activist Аватар для fk0
    Регистрация
    18.02.2005
    Адрес
    St. Petersburg
    Сообщений
    415
    Благодарностей: 3
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    По умолчанию

    Цитата Сообщение от CityAceE
    Хочу высказаться не по содержанию документации, а по её форме. Я за то, чтобы создавать и использовать документацию в формате HTML и на Спектруме, и на ПЦ, то есть иметь единый формат.
    Во-первых -- имеется ли конечная форма представления, подготовленный к публикации вариант, или форма используемая
    при наборе текста? Они могут различаться.

    Я могу сказать, HTML для изначального ввода любых текстов
    пишущихся человеком практически непригоден. Только как
    конечная форма предствления HTML представляет интерес, по
    очевидным причинам (практически везде можно просмотреть
    и распечатать, более-менее легко преобразовать в другую форму).

    В подобной документации используется минимум тэгов, поэтому создать соответсвующий вьювер, который будет поддерживать этот минимум совсем не сложно!
    Почему HTML непригоден: он не позволяет как-то чётко структурировать текст на более глобальном уровне нежели разделение на такие элементы как заголовки, параграфы, списки
    и т.п. Это в свою очередь лишает возможности нумерации разделов
    текста, возможности реализации гиперссылок на конкретный элемент
    текста (именно так, как бы абсурдно не звучало -- HTML не позволит,
    например, сослаться на раздел 1.2 или раздел с таким-то именем,
    только на конкретную точку в тексте), сложно реализовать сноски,
    плавающие комментарии и другие элементы. Плюс трудности с набором формул (MathML поддерживается далеко не везде...)
    И трудности с получением качественных иллюстраций пригодных как для просмотра, так и для печати. Получить из HTML качественно отформатированный, пригодный для печати текст вообще практически невозможно. Единственный известный мне метод -- html2ps выдаёт текст разве что удовлетворительного качества
    (в то время как LaTeX -- отличного). Распечатать же текст из типичного обозревателя, такого как IE или Mozilla без ухищрений
    вообще практически невозможно: дойдёт до того, что даже рисунки
    и таблицы будут рваться посередине страницы.

    Я рассматриваю HTML исключительно как удобное средство для представления на экране, не более того.

    (Кстати, почему бы не создать такой вьювер в рамках ZX SDK?) За то выгода на лицо! Такую документацию можно будет одинаково легко смотреть и на Спектруме, и на ПЦ под разными ОС, а при необходимости и качественно распечатать.
    А имеет ли смысл упираться в HTML? Фактически нужно:

    * представление гипертекста (не обязательно HTML!);

    * желательно иметь возможность представление элементов
    текста непредставимого в plain-text файле, например,
    дополнительные символы, верхние и нижние индексы,
    разные шрифты и цвета -- я говорю желательно,
    но не обязательно;

    * желательно представление иллюстраций.

    Попадались среди электронной прессы для ZX-Spectrum
    экземпляры поддерживающие первый и третий пункт. И была
    ещё в своё время, давно уже (~2000 год), программа, то ли frame maker, то ли paper maker -- для создания электронной "газеты"
    для ZX-Spectrum. Программа спектрумовская, не писишная. Вот
    её вьювер тоже неплох.

    Другое дело, что подготовить такую документацию, без титанических усилий, исключительно на спектруме невозможно...

    И ещё момент. Значительная часть документации просматривается
    непосредственно в ходе написания кода. Это означает, что просматриваться она будет во встроенном реадакторе ассемблера.
    Следовательно, он должен поддерживать такой "формат". Было бы
    замечательно, если бы ALCO добавил в Alasm "двухоконность"
    (когда экран по-вертикали делится на два окна), поддержку цветовых
    кодов из ACEdit, поддержку гипер-ссылок и поддержку вставки
    картинок. Скорей, это получится гибрид из ACEdit и ALASM. Было бы
    здорово.

  7. #6
    Vitamin C++ Аватар для Vitamin
    Регистрация
    14.01.2005
    Адрес
    Таганрог, Россия
    Сообщений
    4,065
    Благодарностей: 1439
    Mentioned
    1 Post(s)
    Tagged
    0 Thread(s)

    По умолчанию

    Цитата Сообщение от fk0
    Было бы
    замечательно, если бы ALCO добавил в Alasm "двухоконность"
    (когда экран по-вертикали делится на два окна), поддержку цветовых
    кодов из ACEdit, поддержку гипер-ссылок и поддержку вставки
    картинок. Скорей, это получится гибрид из ACEdit и ALASM. Было бы
    здорово.
    аласм поставляется не только для 8, но и для 7-пиксельных строк, куда поддержку цветов и картинок не вставишь. да и думаю большие проблемы с цветовыми кодами- текст-то токенизированный! комментарии тоже свой формат имеют

    зы. посмотри мою прогу QHTV. она изначально делалась для просмотра документации. есть все что надо и не надо. единственное серьезное ограничение вижу- размер текста. над этим буду работать.

  8. #7
    Veteran Аватар для GriV
    Регистрация
    18.02.2005
    Адрес
    Набережные Челны
    Сообщений
    1,574
    Благодарностей: 104
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    Thumbs up

    2fk0> система самодокументировния вообще класс, только я не понял как там в детялах - смешивается код и сама прога (при генерировании), но это не самое важное.

    Касательно редактирования/просмотра - действительно просто напросто делать комменты - через те же кривые чертЫ (символы "\") точки с запятой (";") ну и т.п. - в сам редктор будет иметь два сдвигаемых окна - одной поверх другого - когда программист движет курсором в соседнем окне автоматически подгружается (или просто выводится когда оно в памяти) коммент к указанной строчке текста асма. Причём при физической выгрузке на диске как раз будет текст состоять из строк ассемблера перемешанных со строчками помощи, а когда редактируется текст программы то для программиста это прозрачно - у него в соседнем окошке эти комменты.

    При конечном существующем коде можно тоже без вопросов получить чистый код или чистый текст - опять же через парсер.

    Идею поддерживаю, ставлю 5 баллов (-;
    Биты рулят лучше байтов, байты рулят шустрее!
    View, Звук, Цвет

  9. #8
    Veteran Аватар для GriV
    Регистрация
    18.02.2005
    Адрес
    Набережные Челны
    Сообщений
    1,574
    Благодарностей: 104
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    По умолчанию

    касательно конечной формы - внутри текста программы теги никакие не нужны - они просто будут мешать и давать повод очень "разумным" homo какую-нить дурь выдумлять. А во что преобразовать потом полученный от парсера док - это уже личное дело каждого.
    Биты рулят лучше байтов, байты рулят шустрее!
    View, Звук, Цвет

Информация о теме

Пользователи, просматривающие эту тему

Эту тему просматривают: 1 (пользователей: 0 , гостей: 1)

Похожие темы

  1. Документация по Z280
    от spensor в разделе Unsorted
    Ответов: 39
    Последнее: 07.04.2014, 23:52

Ваши права

  • Вы не можете создавать новые темы
  • Вы не можете отвечать в темах
  • Вы не можете прикреплять вложения
  • Вы не можете редактировать свои сообщения
  •