Надеюсь, речь не идет о литературном программировании -
это тупик или нишевое решение для образовательных целей типа "учебник с примерами задач".
...
Конечно нет - т.к. согласен с этой главной мыслью:
...
В наш век документация в виде единой книги, оторванной от исходного кода и от интегрированной среды разработки, уже не актуальна. Учебник в виде книги удобен, но не документация. ...
- потому и предлагаю для программ как раз интеграцию с их математическим и предметно-качественным обоснованием - и соответствующие разновидности вьюшек.
С выносками, как можно видеть, тоже согласен.
И уж конечно саму программу не разбивать на главы...
Напротив, программы погружены в документы среды - каталожные и проектные - и вообще м.б. единственным содержанием документа. Также в документе м.б. всё, что, скажем, уместно в том же учебнике - а программа связывается (в том же или любых других документов) через коммандер и выводит в окно вьюшки. Ну и её структурные единицы обозримы во включающем документе через указатели, аналогичные УСД-шным...
Вместе с тем тут такая штука. Программа ведь в динамике происходит из некоего представления сочинителя - уточняемого с повышением формализованности от предметного до информатического. И надо отразить уровни формализации. Пока вижу такое решение, как здесь:
http://forum.easyelectronics.ru/viewtop ... 26#p204947 - т.е. с одной структурой модели связаны описания на ряде языков, на которых среда в принципе позволяет формализовать. Кто что думает?
Также по поводу этого:
...
Глядя на код в семантическом редакторе, программист должен в первую очередь видеть структурную схему программы, а не plain text комментариев, пространные объяснения гиперссылок или словесный мусор макрокоманд препроцессора. Вот если что-то в схеме непонятно, то можно на соответствующий элемент или связь навести курсор и получить всплывающую подсказку.
...
- структурную схему программы можно понимать по-разному. Как я думаю (исхдя из позиции Лаптева), единая структура - это СД. Но нужно иметь и частные представления - алгоритмов, структур данных, их связывания на заданном исполнителе. И параллельное представление работы пользователя - как взаимодействующей программы-инструкции. Она и будет хелпом (конечно, сообщения программы/среды само собой - и на схеме инструкции они тоже отражаются как основные причины реакций юзера/сисопа).
И то, что неясно из текста (или частично нетекстовой формы исходника) - должно представлять не только предметными (неформальными) и математическими (утверждениями) комментами. Но и производными от исходника схемами (где уместно - таблицами). Обычно их назначение - представление зависимостей программных единиц в конкретном аспекте.
И документ тоже должен схему иметь. По сказанному о редакторе - как единая это тоже СД, поддеревьями которого служат входящие программы (скрипты, частный случай которых - очевидно, коммандеры).
И здесь также только такой схемы мало. Надо также структурировать по тем самым "секциям" (докэлементам УСД-шной иерархии). Надо иметь возможность (для тех же учебных документов) предлагать/предписывать порядки просмотра докэлементов - в т.ч. по выбору читателя. И это тоже удобно показывать схематически...
Ну и препроцессинг должен заменяться конкретизирующей сборкой из каталожных единиц (типовых и оригинальных). При которой отдельные листы/фрагменты из каталога используются повторно - с заполнением трафаретных реквизитов по контексту - хотя бы для того, чтобы в БД среды целиком не дублировать... И схемы для представления сборки тоже удобны...