ZXNet эхоконференция «code.zx»

Hello, All

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

Hello, CityAceE

Cit> Хочу высказаться не по содержанию документации, а по её форме. Я за
Cit> то, чтобы создавать и использовать документацию в формате HTML и на
Cit> Спектруме, и на ПЦ, то есть иметь единый формат.
Cit>

Во-первых -- имеется ли конечная форма представления, подготовленный к
публикации вариант, или форма используемая
при наборе текста? Они могут различаться.

Я могу сказать, 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. Было бы
здорово.

Hello, fk0

По поводу внедрения документации в текст программы всем смотреть 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) документация не оторвана от текста программы (т.е. можно написать
аффигительную генерилку, которая кроме выдирания доки, будет ещё раскрашивать и
форматировать текст программы

Hello, fk0

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

Hello, fk0

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

аласм поставляется не только для 8, но и для 7-пиксельных строк, куда поддержку
цветов и картинок не вставишь. да и думаю большие проблемы с цветовыми кодами-
текст-то токенизированный! комментарии тоже свой формат имеют

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

Hello, GriV

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

Hello, Vitamin

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

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

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

Идею поддерживаю, ставлю 5 баллов (-;