относительно живой проект по улучшению документации Common Lisp

The main reference document for Common Lisp, the legendary CLHS, is: scaring a lot of people away with its outer look straight out of 1996.

недостаточно вебдванольный+? По мне, идеально смотрится в Имаксе.

Ну иногда ещё с навигацией проблемы.
Иногда от какого-то слова [нечто] ссылки ведут на глоссарий, где краткая сводка(в очень общих словах) и всё. Дальше уже нужно какими-то окольными путями искать какие функции есть для работы с этим [нечто], как оно вообще применяется и т.д.

относительно живой проект по улучшению документации относительно живого Common Lisp

Проблема с глоссарием - это да. Лично мне не нравится обилие шрифтов, у меня глаз спотыкается об гиперлинки (я смотрю в браузере).

Но тут про другое в манифесте написано: CLHS нельзя расширить или поменять. Я бы хотел добавить туда «see also», со ссылками на «rosetta code», «computer benchmark game», какие-нибудь «extensible sequences», особенности реализации, augmented environments из cltl2, библиотеки и т.п.

Или просто ввести систему тегов. Но, как я понял, CLHS дубовый и сделать этого нельзя. Очевидная идея состоит в том, чтобы поговорить об этом с Lispworks-ами и попросить у них разрешения. Но чувак перевёл уже полно функций, так что это может быть и не нужно.

Другая возможная идея - показывать CLHS во фрейме (хотя вроде фреймы давно прокляты в веб дизайне, но мои познания в дизайне близки к нулю), а «see also» показывать рядышком. Не знаю, насколько это законно.

Вообще там люди чем-то странным заняты, и по сути они собираются стырить CLHS вручную, поскольку сейчас у них главная задача - это вычитать diff-ы с CLHS

При том, что теховские исходники стандарта вроде как уже доступны здесь

https://gitlab.com/vancan1ty/clstandard_build

В связи с этим напрашивается такой вопрос - насколько хорошо работают конверторы теха в html? Мне кажется, чем вычитывать диффы, нужно просто взять этот конвертор и отконвертировать, а дальше заниматься расстановкой недостающих ссылок.

не хватает отступа слева в дереве

насколько хорошо работают конверторы теха в html

Хорошо работают конвертеры LaTeXа. Чистый тех преобразовывать всё равно, что картинку. Кроме того, в теховском макете нет гиперссылок.

Написал товарищам, что скорее всего, они воруют CLHS - они задумались. https://github.com/phoe/clus-data/issues/24#issuecomment-326377727

Также посмотрел на указанные у них агрегаторы документации, из них quickdocs показался наиболее интересным.

В общем, моё мнение - нужно сделать что-то типа нашего «описания Яра» на том же движке, завести более широкое оглавление, чем в стандарте CL. Для начала каждая статья может содержать докстроку из SBCL, ссылку на CLHS, теги, ссылки «см. также», другие интересные ссылки по этой теме, результаты поиска quickdocs.

Дальше есть два варианта - сгенерировать гигантский сайт по всем возможным идентификаторам и понятиям из quicklisp или сделать библиотечку, к-рая позволит динамически формировать такую страничку из лиспа, подобно тому, как в Яре сейчас работает «поиск по символам». Для этого нужно будет сгенерировать html файл и открыть его системным браузером.

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

Другое дело, располагаю ли лично я ресурсами этим заниматься? Расширить справку по символу в своей IDE можно и это, наверное, нетрудно. А вот создавать какую-то там библиотеку или писать на емакс-лиспе - этим лично я заниматься не буду в обозримом будущем. Если бы у этих парней было всё в порядке с авторскими правами, их система бы работала (пусть даже с огрехами в описаниях) и можно было бы поучаствовать без большой предварительной работы - я бы, пожалуй, уделил бы этому 2-3 часа в неделю. А так - и участвовать не в чем.

писать на емакс-лиспе - этим лично я заниматься не буду в обозримом будущем

Ну условно-встроенный CL в Emacs-е тоже есть:) Так что какую-то часть твоего кода они переиспользовать смогут

Если бы кто-то предложил вариант, как вообще обойтись без того, чтобы мне пришлось кодировать и чтобы остальные тоже могли пользоваться - было бы круто. Мне было бы интересно периодически добавлять ссылки, например, есть понятие Thread. Что про него нужно знать? О нём в стандарте вообще ничего нет. Значит, должна быть обзорная статья про special variables, ссылки на документацию по реализациям, понятие об atomic-ах, ссылки на документацию, ссылка на bordeaux-threads и другие библиотеки по многопоточности (точно помню, что есть ещё одна, более навороченная). Ещё есть cl-cookbock, computer benchmark game, rosetta code. Можно сослаться на аналогичные понятия (call/cc, асинхронщина, iolib).

Набросать такой набор ссылок про треды я мог бы минут за 30, а дальше что делать с ним? НЕкуда его вписать.

Если бы кто-то предложил вариант, как вообще обойтись без того, чтобы мне пришлось кодировать и чтобы остальные тоже могли пользоваться - было бы круто. Мне было бы интересно периодически добавлять ссылки, например, есть понятие Thread.

Пиши себе на cliki.net, да пиши - людям на пользу:) Кто тебе мешает то? Против свободного контента они никогда не возражали. Да и сослаться на сопутствующие библиотеки там проще будет. Там например лежит уже Proposed issues, perhaps for a future revision of the Common Lisp standard: и Proposed ANSI Revisions and Clarifications
Или допустим Learn Lisp The Hard Way принимает PR-ы для книги об экосистеме CL. У них рядом и зачаточный индекс в CLHS стиле имеется.

Насчёт Cliki - это вроде ничего, но одной вещи не хватает. Я пишу в поисковике «destructuring-bind» и не вижу ссылки на CLHS. Далее, я пишу user-agent и не вижу ничего, хотя такой символ есть в hunchentoot. Т.е. всё же не полностью совершенно.

Относительно Learn Lisp The Hard Way - зашёл в реп, нажал пару ссылок, увидел 404, закопать.

Относительно Learn Lisp The Hard Way - зашёл в реп, нажал пару ссылок, увидел 404, закопать.

Так его установить и запустить надо. RTFM, однако.

P.S. Ну или научи github по ссылке открывать .md, если расширение не указано.

Ну, на битбукете все ссылки из md в md работают, я ожидал этого и от данного проекта. Если его надо скачать и запустить, это опять же недостаточный уровень комфорта. У них есть ссылка на http://learnlispthehardway.org/, но у меня это 502.

Ну, на битбукете все ссылки из md в md работают

Нет, не работают: https://bitbucket.org/budden/clcon/src/723e239786e6b98e5e96337926b3ec45ee4db5...

Также приходится явно писать .md. А если ожидается, что из этого будет компилироваться html, то решения также нет.

Если его надо скачать и запустить, это опять же недостаточный уровень комфорта.

Написано же: «hard way».

У них есть ссылка на http://learnlispthehardway.org/, но у меня это 502.

http://web.archive.org/web/20170705102327/http://learnlispthehardway.org/book/ работает

Нет, не работают:

Хорошо, некоторые не работают. Но на главной странице всё построено на этих ссылках. Проблема md/html понятна, им прощу. Неработающий сайт - не прощу.

Проблема md/html понятна, им прощу. Неработающий сайт - не прощу.

Я же ссылку дал: http://web.archive.org/web/20170705102327/http://learnlispthehardway.org/book/

Там всё работает.

Я понял. Но это значит «раньше работало, а теперь не работает». Или ты хочешь сказать, что эта проблема связана с доступом из России?

Нет. Действительно не работает. У них с хостингом какая-то проблема (видимо некому заниматься).

Так они давно веб-версию сломали. Я почему и даю ссылки на github напрямую. Но у меня md-шки окрываюся безпроблемно уже отформатированые.

Они отдельно открываются, а ссылки между ними открываются? Но не суть. Будет веб-версия - будет и предмет для разговора :)

В современном мире, мне кажется, не работает подход «вот я напишу книгу, а потом её опубликую». Как только есть что-то полезное, нужно выпускать версию 0.00, тем самым обретать контент и коллабораторов. А в реальности я вижу аж два проекта, оба в этом смысле дохлые. Т.е. титаническая работа, возможно, идёт, а на поверхности пшик, потому что «некогда настроить гиперссылки» и «некому заниматься хостингом». Сие есть прескорбие.

а ссылки между ними открываются?

И ссылки между ними. По крайней мере у меня. Иначе бы я упомянал об этой штуке.

https://github.com/LispTO/llthw/blob/master/book/1-01-05-symbols.md - тут открываются?

Забавно. Теперь и у меня ничего не открывается.

Как только есть что-то полезное, нужно выпускать версию 0.00, тем самым обретать контент и коллабораторов. А в реальности я вижу аж два проекта, оба в этом смысле дохлые.

По моему пример llthw как раз опровергает идею «выпускать версию 0.00, тем самым обретать контент и коллабораторов». Автор выложил его в 2013 году. С тех пор появился только один коллаборатор, который сделал 62 комита. Весь остальной материал (около тысячи комитов) автор сделал в одиночку. В августе 2015 года ему это надоело и с тех пор проект можно считать мёртвым.

https://github.com/LispTO/llthw/graphs/contributors

А если бы придерживался подхода «вот я напишу книгу, а потом её опубликую», то с большой вероятностью первая версия была бы уже рабочей (без мёртвых ссылок и заглушек для примеров) и легче было бы её рекламировать.

Мне это что-то смутно напоминает, я подумаю.

«вот я напишу книгу, а потом её опубликую», то с большой вероятностью первая версия была бы уже рабочей

Почему? Мне кажется, что вывод должен быть противоположным: с большой вероятностью книги вообще не было бы. А так хоть что-то есть.

Мотивации больше. Вот сделал я https://github.com/Kalimehtar/gtk-cffi и https://github.com/Kalimehtar/gls. И доделывать мотивации нет. Потому что, раз никто не дописывает и не пишет, что не всё работает, значит, наверное, никому не надо. А если никому не надо ,зачем писать.

А, например, https://github.com/Kalimehtar/advanced-readtable я выкладывал уже в рабочем состоянии. И это практически единственный мой проект доделанный до конца и с адекватной документацией.

Потому что, раз никто не дописывает и не пишет, что не всё работает, значит, наверное, никому не надо. А если никому не надо ,зачем писать.

По первой ссылке всё-таки два ишью и один пул реквест имеются.

Аргументацию понял, но очевидно, что оно сильно от человека зависит. Замахнуться на здоровый кусок работы и пилить его никому не показывая у меня энтузиазма не хватило бы.

По первой ссылке всё-таки два ишью и один пул реквест имеются.

Они обработаны. Хотя да, закрыть надо бы.

Замахнуться на здоровый кусок работы и пилить его никому не показывая у меня энтузиазма не хватило бы.

Вот здесь и есть подвох. Когда замахиваешься на здоровый кусок, то подсознательно ждёшь помощи или хотя бы поддержки. А окружающие реагируют в стиле «зашёл в реп, нажал пару ссылок, увидел 404, закопать» (с) den73.

А поддержка может быть только когда проект становится достаточно зрелым (то есть у него нормальная документация, все основные функции работают надёжно и без ошибок). Так какой смысл выкладывать недоделку, чтобы её обхаяли?

Ещё один момент против досрочного выкладывания (особенно библиотек). Если ты что-то выложил, то изменение API становится затруднено. В том смысле, что если кто-то уже начал пользоваться библиотекой, а ты внезапно поменяешь модель её использования, то заставишь этого пользователя переписывать свою программу, а это невежливо.

Соответственно, пока не известно точно API использования (а на начальной стадии разработки без проектирования оно редко известно), лучше не выкладывать.

А окружающие реагируют в стиле «зашёл в реп, нажал пару ссылок, увидел 404, закопать» (с) den73.

И это более-менее нормально, хотя лучше, конечно, написать авторам.

Вот смотри: сейчас у меня основной язык - это Rust. Инфраструктура довольно сырая, хотя при отсутствии альтернатив алгоритм поиска от языка зависеть не будет, разница только в вероятности найти более вылизанную библиотеку. Так вот, если мне что-то надо, то смотрю на готовые решения, на имеющуюся функциональность, скорость реакции на ишью и пул реквесты. Как правило, сам завожу ишью на то чего мне не хватает и смотрю на реакцию автора. Дальше уже по обстоятельствам: или пул реквесты засылаю или форкаю и допиливаю или, если всё совсем плохо, просто локально решаю проблему.

Так какой смысл выкладывать недоделку, чтобы её обхаяли?

Так может оно действительно никому не нужно?

Ну и давай с другой стороны зайдём: предположим, нет никакого решения для определённой проблемы. Если все будут молча писать код, то через какое-то (возможно, долгое) время появится N конкурирующих решений и не факт, что от этой конкуренции будет польза: даже если ты видишь, что твоё решение хуже, то бросать его может быть жалко.

А вот если выкатить сначала «недоделку», то люди могут и присоединиться. Хотя, насколько я могу судить, делать свой проект привлекательным для контрибьюторов - это тоже достаточно сложная задача. Не все могут или хотят этим заниматься, ну тогда как повезёт.

Если ты что-то выложил, то изменение API становится затруднено.

Дык, есть же версионирование. Если инфраструктура языка позволяет с ним нормально работать и автор его соблюдает, то особых проблем быть не должно.

Опять же, сошлюсь на раст, где большинство библиотек не доросли до версии 1.0 и часто друг от друга зависят. И всё более-менее работает.

А вот если выкатить сначала «недоделку», то люди могут и присоединиться. Хотя, насколько я могу судить, делать свой проект привлекательным для контрибьюторов - это тоже достаточно сложная задача. Не все могут или хотят этим заниматься, ну тогда как повезёт.

http://www.cliki.net/GTK binding — здесь 9 дублирующих проектов. Плюс https://github.com/andy128k/cl-gobject-introspection. И все померли от старости (включая мой). Спустя некоторое время, кто-то решит, что нужен хоть один работающий и запилит 10-й. Который тоже проживёт год-два.

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

Может в этом дело.

Дык, есть же версионирование. Если инфраструктура языка позволяет с ним нормально работать и автор его соблюдает, то особых проблем быть не должно.

А толку-то. Выложил версию 0.0.1, затем 0.0.2. Кто-то начал использовать. Затем понял, что накосячил с API и работать неудобно, выложил 0.1.0. Тем, кто работал с 0.0.2 на неё не перейти. Потом обнаружил ошибку, исправил, выложил 0.1.1. Потом добавил функцию, выложил 0.1.2. И тем, кто использовал 0.0.2 либо делать обратный перенос изменений (как делает Debian), что крайне трудно (особенно с учётом изменения структуры, API ведь не просто так меняется), либо смириться с тем, что у них будет вечно глючная и недоделанная версия.

Вот поэтому когда видят библиотеку в состоянии альфа/бета семь раз думают перед тем как использовать. Причём если альтернатив нет, то часто делают свой велосипед. Потому что в нём, если что, проще разобраться.

раст, где большинство библиотек не доросли до версии 1.0 и часто друг от друга зависят. И всё более-менее работает.

Здесь, насколько я понимаю, всё более-менее централизовано. Как в Racket или Haskell. И выкладывают готовое. Смотрю, например, https://crates.io/crates/dlopen. Выложено сегодня, есть документация, примеры, тесты. А то, что номер 0.1, так там у всего в момент релиза 0.1.

Спустя некоторое время, кто-то решит, что нужен хоть один работающий и запилит 10-й. Который тоже проживёт год-два.

Возможно, так. Но если этот кто-то вместо «хотя бы» форкнет один из имеющихся проектов и слегка его допилит, то всё равно неплохо будет. Следующему человеку будет проще, даже если автор забросит своё детище навсегда.

Затем понял, что накосячил с API и работать неудобно, выложил 0.1.0. Тем, кто работал с 0.0.2 на неё не перейти.

Так ведь тут дело не совсем в непродуманности. Возьмём Qt - проект «зрелый», поддерживаемый на коммерческой основе. И ведь всё равно были (и готов спорить, что будут) ломающие изменения. Я очень сомневаюсь, что «продумать всё наперёд» можно в принципе. Опять же, если варишься в собственном соку, то после релиза может выясниться, что куча народу хотели бы использовать твою библиотеку «слегка» иначе.

Мне кажется, всё что тут можно сделать - это облегчить процесс перехода на новую версию.

Смотрю, например, https://crates.io/crates/dlopen. Выложено сегодня, есть документация, примеры, тесты. А то, что номер 0.1, так там у всего в момент релиза 0.1.

Кстати, пример так себе. Знаю по меньшей мере три других библиотеки, которые решают эту задачу и нигде из ридми не понятно какую именно проблемы решает автор этой новой библиотеки. В README.md так вообще сишный пример, который показывает «как всё плохо», но при этом не говорится как ситуация улучшена. В доке путаница со ссылками и т.д.

Конечно, если есть готовая инфраструктура для создания и публикации документации, тестирования и прочего, то забивать на это будут режe и это хорошо, но ещё не гарантирует качество.

Следующему человеку будет проще, даже если автор забросит своё детище навсегда.

Без подробной документации, почему так сделано, и без автора очень тяжело. Я вот сейчас переношу pcc на лисп, так ощущение такое, что проще было бы с нуля написать.

Так ведь тут дело не совсем в непродуманности. Возьмём Qt - проект «зрелый», поддерживаемый на коммерческой основе.

Я про другое. Если сделал проект на Qt4, а вышел Qt5, то, во-первых, исправления ошибок для старой версии всё равно выходят, во-вторых, так как продукт зрелый, то вероятность наткнуться на ошибку ничтожна. А если сделал на основании чего-нибудь версии 0.1, то скорее всего библиотека ещё сыра и будут исправления, причём будут они только в последней версии.

Знаю по меньшей мере три других библиотеки, которые решают эту задачу и нигде из ридми не понятно какую именно проблемы решает автор этой новой библиотеки.

Значит всё-таки не очень централизованно. Я думал, что при принятии на crate кто-то пакет рецензирует.

Я думал, что при принятии на crate кто-то пакет рецензирует.

Нет и у этого есть свои плюсы. Но у библиотек есть «рейтинг», самые популярные так вообще включают в особый список, так что не всё так плохо.