Здравствуйте, Marty, Вы писали:
M>Допустим, что-то описываю в доке, но дублировать какую-то инфу из сорцов не хочется, хочется подтянуть оттуда прямо в виде фрагмента сорца. Сложность в том, что сорцы меняются, номера строк съезжают, актуальное состояние поддерживать нереально в ссылках на номера строк.
Здравствуйте, Marty, Вы писали:
M>>Допустим, что-то описываю в доке, но дублировать какую-то инфу из сорцов не хочется, хочется подтянуть оттуда прямо в виде фрагмента сорца. Сложность в том, что сорцы меняются, номера строк съезжают, актуальное состояние поддерживать нереально в ссылках на номера строк.
M>Кстати, нашел у микрософта: M>https://learn.microsoft.com/ru-ru/contribute/content/code-in-docs#in-repo-snippet-references
Затем выберите, какие строки кода нужно включить в фрагмент, используя Параметры: идентификатор, диапазон и нет.
"Диапазон" это строки, которые ты не хочешь ("съезжают").
"Нет" это "нет".
Остаются идентификаторы. Про которые с самого начала было сказано, что они зависят от формата, а во многих форматах (например, HTML) их использование является плохой практикой.
Re[3]: Ссылки на произвольные фрагменты текста/сорцов/etc
A>"Диапазон" это строки, которые ты не хочешь ("съезжают").
A>"Нет" это "нет".
A>Остаются идентификаторы. Про которые с самого начала было сказано, что они зависят от формата, а во многих форматах (например, HTML) их использование является плохой практикой.
Я не говорю, что это идеал, но раз так сделали, то наверное с этим жить можно. Не обязательно брать идею целиком, но что-то стырить наверное можно
Здравствуйте, Marty, Вы писали:
M>>>Предлагаю пофлеймить, как бы это можно было бы сделать
_>>Скриптами (perl/lua/php/python/js/...).
M>Реализация не принципиальна
_>>Что бы можно было ссылаться на куски кода добавьте в код якоря на которые вы хотите ссылаться
M>Предположим, якорей нет — я пишу доку на сорцы, которые не могу трогать. Например, сорцы тупо чужие, и следующий апдейт перетрёт все мои якоря, если я их сам расставлю
После внедрения якорей сделать дифф, накладывать его после изменения.
Re[4]: Ссылки на произвольные фрагменты текста/сорцов/etc
Здравствуйте, Marty, Вы писали:
M>Я не говорю, что это идеал, но раз так сделали, то наверное с этим жить можно. Не обязательно брать идею целиком, но что-то стырить наверное можно
Я в самом начале писал:
Оставлять какую-нибудь метку в комментах, по ней потом и искать.
Ты ответил:
С меткой любой дурак сможет
Что изменилось? Таже метка в комментарии.
PS: в конце по ссылке табличка в которой указана 1С.
Re[4]: Ссылки на произвольные фрагменты текста/сорцов/etc
Здравствуйте, Marty, Вы писали:
A>>"Диапазон" это строки, которые ты не хочешь ("съезжают"). A>>"Нет" это "нет". A>>Остаются идентификаторы. Про которые с самого начала было сказано, что они зависят от формата, а во многих форматах (например, HTML) их использование является плохой практикой.
M>Я не говорю, что это идеал, но раз так сделали, то наверное с этим жить можно. Не обязательно брать идею целиком, но что-то стырить наверное можно
Причём здесь идеал или не идеал. Я говорю, что это подтверждает написанное ранее, что надо привязываться к формату, а для тех форматов, где идентификаторов нет или они нежелательны, придётся ограничиваться ненадёжной альтернативой в виде хешей узлов. Если бы можно было придумать что-то лучше, так придумали бы, наверно.
Re: Ссылки на произвольные фрагменты текста/сорцов/etc
Здравствуйте, Marty, Вы писали:
M>Предлагаю пофлеймить, как бы это можно было бы сделать
А если наоборот, делать документацию прямо в чужом коде чтобы получалось как в Qt или doxygen, хранить сделанную документацию как git patch, при выходе новых исходников применять патч, не применился править документацию и делать новый патч.
Re[2]: Ссылки на произвольные фрагменты текста/сорцов/etc
Здравствуйте, Igore, Вы писали:
M>>Предлагаю пофлеймить, как бы это можно было бы сделать I>А если наоборот, делать документацию прямо в чужом коде чтобы получалось как в Qt или doxygen, хранить сделанную документацию как git patch, при выходе новых исходников применять патч, не применился править документацию и делать новый патч.
Я думал об этом, но это тот путь, когда сорцы не документированы вообще. И мне как-то это показалось геморойно.
А в этом топике речь идёт о какой-то дополнительной документации, даже если сорцы все продокументированы, всегда есть что добавить в плане каких-то общих сведений
Здравствуйте, Marty, Вы писали:
M>Допустим, что-то описываю в доке, но дублировать какую-то инфу из сорцов не хочется, хочется подтянуть оттуда прямо в виде фрагмента сорца. Сложность в том, что сорцы меняются, номера строк съезжают, актуальное состояние поддерживать нереально в ссылках на номера строк.
1. У меня в Emacs есть следующий хоткей: вычисляется bitbucket/gitlab/etc url на текущий файл проекта, в URL входит сам путь к файлу, текущая ревизия, и номер строки (или же несколько строк если активна область выделения), и этот url сразу же открывается в браузере. Это очень удобно когда нужно коллеге по чату отправить позицию в каком-нибудь файле.
Можно вставлять в документацию и строки не съедут, но из-за фиксированной ревизии ссылка будет со временем "устаревать", так как указывает на старую версию файла.
2. В Org-mode есть ссылки в которые входит путь к локальному файлу и текст/regexp поиска, поэтому при изменении файла с большой вероятностью ничего не съедет. Я такие ссылки использую в своих локальных заметках. https://orgmode.org/manual/Search-Options.html
Re[2]: Ссылки на произвольные фрагменты текста/сорцов/etc
Здравствуйте, Igore, Вы писали:
M>>Предлагаю пофлеймить, как бы это можно было бы сделать I>А если наоборот, делать документацию прямо в чужом коде чтобы получалось как в Qt или doxygen, хранить сделанную документацию как git patch, при выходе новых исходников применять патч, не применился править документацию и делать новый патч.
