Цитата Сообщение от 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. Было бы
здорово.