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 баллов (-;