docs: Added the report - #1
Open
danisaev wants to merge 14 commits into
Open
Conversation
gsvgit
requested changes
May 7, 2026
gsvgit
left a comment
gsvgit
left a comment
Owner
There was a problem hiding this comment.
- В работе не должно быть "не определённых" терминов, сокращений и т.д. Если надо, давайте опредедения (пучть и не очень формальные), приводите ссылки на ресурсы, где можно узнать подробнее.
- Запланируйте структуру текста так, чтобы избежать повторений и непоследовательных переходов.
- Чётко разделите "что сделано", "зачем сделано", "как сделано".
|
|
||
| \section{Постановка задачи} | ||
|
|
||
| Работа выполняется в проекте UCFS. \textbf{Целью работы является} создание простых примеров использования инструмента, включая реализацию кода и интеграцию инструкции по запуску в основную документацию. |
Owner
There was a problem hiding this comment.
Ссылка на UCFS. А то не понятно, что за проект. Ну и пару слов о том, что это за проект. А то дальше Вы говорите про примеры использования. А для чего его используют?
|
|
||
| Предлагаемое решение заключается в создании набора минимальных и понятных примеров, которые позволяют последовательно познакомиться с возможностями UCFS. В отличие от существовавших ранее сложных примеров, разработанные сценарии намеренно упрощены: графы невелики по размеру, а их структура интуитивно понятна. Ключевым примером выбрана грамматика $a^nb^n$ --- она не имеет принципиального значения для демонстрации возможностей инструмента, но была взята из учебного пособия\footnote{Ссылка на пособие: \url{https://github.com/FormalLanguageConstrainedPathQuerying/FormalLanguageConstrainedReachability-LectureNotes} (дата обращения: 11.03.2026).}, что обеспечивает методическую обоснованность выбора. Для описания грамматики использовался встроенный DSL проекта UCFS, а графы представлены в формате \texttt{.dot}. | ||
|
|
||
| Принятые решения обоснованы следующим образом: простота примеров снижает порог входа и подготавливает новых пользователей к работе со сложными графами, имеющими практическое применение. Интеграция инструкции по запуску непосредственно в основной файл README (вместе с визуализациями графов в формате SVG) устраняет необходимость поиска отдельной документации. |
Owner
There was a problem hiding this comment.
Не надо в десятый раз повтроять про пониженеи порога входа. У Вас короткий отчёт. Структурируйте его так, чтобы избежать повторов.
Owner
There was a problem hiding this comment.
И тут оказывается, что то-то рисовали в SVG. Опишите перед этим архитектуру документации, которую Вы создали.
|
|
||
| \section{Апробация} | ||
|
|
||
| Проверка разработанных примеров осуществлялась следующим образом. Каждый граф был вручную исследован на корректность структуры, после чего с помощью инструмента UCFS для него был получен SPPF (Shared Packed Parse Forest). Ручной разбор полученного SPPF дал результаты, идентичные результатам исходного поиска по графу, что подтверждает корректность работы примеров. |
|
|
||
| \section{Описание предлагаемого решения} | ||
|
|
||
| UCFS представляет собой инструмент для работы с задачами на пересечении контекстно-свободных языков и ориентированных графов с метками на рёбрах, основанный на алгоритме GLL. До выполнения данной работы в проекте уже существовали примеры использования, однако они были сложными и громоздкими, что затрудняло начальное освоение инструмента. Аналоги из других проектов часто страдают той же проблемой: отсутствие простых, наглядных сценариев повышает порог входа для новых пользователей. |
|
|
||
| \section{Апробация} | ||
|
|
||
| Проверка разработанных примеров осуществлялась следующим образом. Каждый граф был вручную исследован на корректность структуры, после чего с помощью инструмента UCFS для него был получен SPPF (Shared Packed Parse Forest). Ручной разбор полученного SPPF дал результаты, идентичные результатам исходного поиска по графу, что подтверждает корректность работы примеров. |
|
|
||
| Запуск примеров выполняется единой командой через консольный сценарий. Несмотря на отсутствие формальных отзывов от сторонних пользователей, проблем с переносимостью и запуском на других устройствах ожидаться не должно благодаря стандартизированному формату графов (\texttt{.dot}) и отсутствию внешних зависимостей, специфичных для окружения разработки. | ||
|
|
||
| Оценка успешности работы проводилась по следующим критериям: все примеры успешно запускаются, результаты их работы совпадают с ожидаемыми, а обновлённый файл README стал более понятным для начинающих пользователей. |
|
|
||
| \section{Заключение} | ||
|
|
||
| В ходе выполнения работы получены следующие результаты: |
Owner
There was a problem hiding this comment.
Ничего не сказано про реструктуризацию существовавших примеров.
Owner
|
Сперва пичините CI |
Owner
|
И конфликты порешайте. |
gsvgit
requested changes
Jun 12, 2026
|
|
||
| \section{Постановка задачи} | ||
|
|
||
| Работа выполняется в проекте UCFS\footnote{Ссылка на UCFS: \url{https://github.com/FormalLanguageConstrainedPathQuerying/UCFS}}. UCFS — это универсальный инструмент, предназначенный для решения задач, которые лежат на пересечении контекстно-свободных языков и ориентированных графов с метками на ребрах. В основе его работы лежит алгоритм GLL (Generalized LL parsing) — алгоритм синтаксического анализа, обобщающий LL-парсинг на случай неоднозначных грамматик и позволяющий эффективно работать с контекстно-свободными языками на графах. Этот инструмент применим для широкого круга задач. Среди ключевых примеров можно выделить синтаксический анализ, а также контекстно-свободную навигацию по графам (CFPQ/CFL–R). \textbf{Целью работы является} создание простых примеров использования инструмента, включая реализацию кода и интеграцию инструкции по запуску в основную документацию. |
Owner
There was a problem hiding this comment.
Тире нейроночные. Неразрывные пробелы.
- Replaced "парсинг" with "анализ" - Added dashes and non-portable spaces
gsvgit
requested changes
Jun 15, 2026
|
|
||
| \textbf{Целью работы является} создание пошаговой инструкции по аналогии с популярными библиотеками, а также простых примеров использования инструмента UCFS, включая реализацию кода и интеграцию инструкции по запуску в основную документацию. | ||
|
|
||
| \textbf{Для достижения цели требуется решить следующие задачи:} |
|
|
||
| В других проектах, таких как NetworkX\footnote{Ссылка на документацию NetworkX: \url{https://networkx.org/documentation/stable/}}, стандартной практикой является наличие разделов \enquote{Tutorial}, в котором содержится инструкция по работе с инструментом, и \enquote{Getting Started} с минимальными воспроизводимыми примерами, которые демонстрируют базовый API. В данном проекте вышеперечисленные разделы отсутствуют. | ||
|
|
||
| \textbf{Вывод:} Таким образом, в текущем виде документация UCFS не подходит для быстрого старта, и возникает необходимость в создании упрощенных учебных сценариев с пошаговой инструкцией по запуску. |
Owner
There was a problem hiding this comment.
Да не надо писать "Вывод:". пишите нормальный текст.
|
|
||
| \section{Тестирование} | ||
|
|
||
| Проверка разработанных примеров осуществлялась посредством тестирования. Каждый граф был вручную исследован на корректность структуры, после чего с помощью инструмента UCFS для него был получен SPPF~(Shared Packed Parse Forest~--- общий упакованный лес разбора). Анализ полученного SPPF показал, что результаты совпадают с ожидаемыми результатами поиска по графу, что подтверждает корректность работы примеров. |
Owner
There was a problem hiding this comment.
"общий упакованный лес разбора" -- нет)
|
|
||
| \section{Заключение} | ||
|
|
||
| В ходе выполнения работы получены следующие результаты: |
|
|
||
| В ходе выполнения работы получены следующие результаты: | ||
|
|
||
| \begin{itemize} |
Owner
There was a problem hiding this comment.
А результаты полностью соответствуют задачам?
Author
|
Касательно последнего комментария о соответствии результатов задачам, постарался переделать, но заведомо не вносил неотчуждаемый результат типо "обозрел, изучил и тп." Если результаты должны это содержать, готов в кратчайшие сроки исправить. |
vkutuev
suggested changes
Jul 15, 2026
|
|
||
| \section{Введение} | ||
|
|
||
| Работа выполняется в рамках проекта UCFS\footnote{Ссылка на UCFS: \url{https://github.com/FormalLanguageConstrainedPathQuerying/UCFS}}. UCFS~--- это универсальный инструмент, предназначенный для решения задач, которые лежат на пересечении контекстно-свободных языков и ориентированных графов с метками на ребрах. В основе его работы лежит алгоритм GLL~(Generalized LL parsing)~--- алгоритм синтаксического анализа, обобщающий LL-анализ на случай неоднозначных грамматик. Этот инструмент применим для широкого круга задач, включая синтаксический анализ и контекстно-свободную навигацию по графам (CFPQ/CFL-R). |
There was a problem hiding this comment.
задач, которые лежат на пересечении контекстно-свободных языков и ориентированных графов с метками на ребрах
Очень странная формулировка
В основе его работы лежит алгоритм GLL~(Generalized LL parsing)~--- алгоритм синтаксического анализа, обобщающий LL-анализ на случай неоднозначных грамматик.
Это правда, но GLL — алгоритм синтаксического анализа, тут же ещё и его обобщение на графы никак не упомянуто
контекстно-свободную навигацию по графам (CFPQ/CFL-R)
Тоже что-то странное и не очень принятое в русскоязычной литературе. А "CFPQ/CFL-R" — аббревиатуры, которые не раскрыты
|
|
||
| Работа выполняется в рамках проекта UCFS\footnote{Ссылка на UCFS: \url{https://github.com/FormalLanguageConstrainedPathQuerying/UCFS}}. UCFS~--- это универсальный инструмент, предназначенный для решения задач, которые лежат на пересечении контекстно-свободных языков и ориентированных графов с метками на ребрах. В основе его работы лежит алгоритм GLL~(Generalized LL parsing)~--- алгоритм синтаксического анализа, обобщающий LL-анализ на случай неоднозначных грамматик. Этот инструмент применим для широкого круга задач, включая синтаксический анализ и контекстно-свободную навигацию по графам (CFPQ/CFL-R). | ||
|
|
||
| На данный момент проект обладает широкой функциональностью, однако существующие примеры использования сложны, так как решают конкретную узкую задачу и не позволяют новым пользователям разобраться в использовании инструмента. Данная практика направлена на улучшение документации и создание пошаговой инструкции использования инструмента, которая завершается запуском простых примеров, что позволит быстрее освоить инструмент и начать применять его в учебных и исследовательских задачах. |
There was a problem hiding this comment.
существующие примеры использования сложны, так как решают конкретную узкую задачу
Кажется, в этом и суть примеров (новые тоже решают какую-то конкретную задачу). Может быть что-то другое имелось в виду, тогда стоит переформулировать
| \textbf{Для достижения цели требуется решить следующие задачи.} | ||
| \begin{enumerate} | ||
| \item Изучить материалы, касающиеся контекстно-свободных грамматик и языков. | ||
| \item Выполнить обзор существующих примеров UCFS и подходов к написанию документации в популярных проектах. |
There was a problem hiding this comment.
подходов к написанию документации в популярных проектах
Кажется, этого обзора не было (только NetworkX упоминается)
| \begin{enumerate} | ||
| \item Изучить материалы, касающиеся контекстно-свободных грамматик и языков. | ||
| \item Выполнить обзор существующих примеров UCFS и подходов к написанию документации в популярных проектах. | ||
| \item Сформулировать требования к документации для быстрого старта и спроектировать формат интеграции учебных примеров. |
There was a problem hiding this comment.
Сформулированных требований я что-то тоже не вижу
|
|
||
| \section{Описание предлагаемого решения} | ||
|
|
||
| Предлагаемое решение заключается в создании документации, подробно поясняющей каждый шаг нового пользователя для начала работы с UCFS, а именно базовую информацию о CFL~(Context-Free Languages), инструкцию по заданию графов и грамматик, инструкцию по чтению выходных данных, а также содержащую набор минимальных и понятных примеров, которые позволяют последовательно познакомиться с возможностями UCFS. В отличие от существовавших ранее сложных примеров, разработанные сценарии намеренно упрощены:~графы невелики по размеру, а их структура интуитивно понятна. Ключевым примером выбрана грамматика $a^nb^n$~--- она не имеет принципиального значения для демонстрации возможностей инструмента, но была взята из учебного пособия\footnote{Ссылка на пособие: \url{https://github.com/FormalLanguageConstrainedPathQuerying/FormalLanguageConstrainedReachability-LectureNotes} (дата обращения:~14.03.2026).}, что обеспечивает методическую обоснованность выбора. Для описания грамматики использовался встроенный DSL проекта UCFS, а графы представлены в формате~\texttt{.dot}. |
There was a problem hiding this comment.
базовую информацию о CFL~(Context-Free Languages)
Может быть как-то русскоязычный термин в первую очередь использовать?
грамматика
$a^nb^n$ ~--- она не имеет принципиального значения для демонстрации возможностей инструмента, но была взята из учебного пособия\footnote{Ссылка на пособие: \url{https://github.com/FormalLanguageConstrainedPathQuerying/FormalLanguageConstrainedReachability-LectureNotes}
В пособии эта грамматика мелькает 1 раз, причём пример отличается. Может быть стоит более конкретно описать мотивацию? Это же простейшая КС-грамматика
|
|
||
| Предлагаемое решение заключается в создании документации, подробно поясняющей каждый шаг нового пользователя для начала работы с UCFS, а именно базовую информацию о CFL~(Context-Free Languages), инструкцию по заданию графов и грамматик, инструкцию по чтению выходных данных, а также содержащую набор минимальных и понятных примеров, которые позволяют последовательно познакомиться с возможностями UCFS. В отличие от существовавших ранее сложных примеров, разработанные сценарии намеренно упрощены:~графы невелики по размеру, а их структура интуитивно понятна. Ключевым примером выбрана грамматика $a^nb^n$~--- она не имеет принципиального значения для демонстрации возможностей инструмента, но была взята из учебного пособия\footnote{Ссылка на пособие: \url{https://github.com/FormalLanguageConstrainedPathQuerying/FormalLanguageConstrainedReachability-LectureNotes} (дата обращения:~14.03.2026).}, что обеспечивает методическую обоснованность выбора. Для описания грамматики использовался встроенный DSL проекта UCFS, а графы представлены в формате~\texttt{.dot}. | ||
|
|
||
| Принятые решения обоснованы следующим образом:~простота примеров снижает порог входа и подготавливает новых пользователей к работе со сложными графами, имеющими практическое применение. Интеграция инструкции по запуску непосредственно в основной файл документации (вместе с визуализациями графов в формате~SVG)~устраняет необходимость поиска отдельной информации. |
There was a problem hiding this comment.
В этой строке как-то много неразрывных пробелов. Точно ли они здесь уместны?
|
|
||
| В других проектах, таких как NetworkX\footnote{Ссылка на документацию NetworkX: \url{https://networkx.org/documentation/stable/}}, стандартной практикой является наличие разделов \enquote{Tutorial}, в котором содержится инструкция по работе с инструментом, и \enquote{Getting Started} с минимальными воспроизводимыми примерами, которые демонстрируют базовый API. В данном проекте вышеперечисленные разделы отсутствуют. | ||
|
|
||
| Таким образом, в текущем виде документация UCFS не подходит для быстрого старта, и возникает необходимость в создании упрощенных учебных сценариев с пошаговой инструкцией по запуску. |
There was a problem hiding this comment.
Таким образом, в текущем виде документация UCFS не подходит для быстрого старта
Кажется, к этому выводу уже во введении пришли. Если что-то другое имелось в виду, надо переформулировать
|
|
||
| Принятые решения обоснованы следующим образом:~простота примеров снижает порог входа и подготавливает новых пользователей к работе со сложными графами, имеющими практическое применение. Интеграция инструкции по запуску непосредственно в основной файл документации (вместе с визуализациями графов в формате~SVG)~устраняет необходимость поиска отдельной информации. | ||
|
|
||
| Реализация решения осуществлялась с использованием языка Kotlin~(код примеров), DSL для задания грамматики, формата~\texttt{.dot} для описания графов, консольной утилиты dot~(Graphviz)~для конвертации графов в SVG и Markdown для оформления документации. |
There was a problem hiding this comment.
dot~(Graphviz)~для
Снова сомнительные неразрывные пробелы
Markdown для оформления документации
Может mkdocs упомянуть, как технологию?
|
|
||
| \section{Тестирование} | ||
|
|
||
| Проверка разработанных примеров осуществлялась посредством тестирования. Каждый граф был вручную исследован на корректность структуры, после чего с помощью инструмента UCFS для него был получен SPPF~(Shared Packed Parse Forest). Анализ полученного SPPF показал, что результаты совпадают с ожидаемыми результатами поиска по графу, что подтверждает корректность работы примеров. |
There was a problem hiding this comment.
Проверка разработанных примеров осуществлялась посредством тестирования.
Может хоть сказать, что "ручного тестирования", иначе предложение балансирует между очевидным и бредовым
результаты совпадают с ожидаемыми результатами
Это точно надо переформулировать
|
|
||
| Проверка разработанных примеров осуществлялась посредством тестирования. Каждый граф был вручную исследован на корректность структуры, после чего с помощью инструмента UCFS для него был получен SPPF~(Shared Packed Parse Forest). Анализ полученного SPPF показал, что результаты совпадают с ожидаемыми результатами поиска по графу, что подтверждает корректность работы примеров. | ||
|
|
||
| Запуск примеров выполняется единой командой через консольный сценарий. Проверка переносимости показала, что проблем с запуском не возникает благодаря стандартизированному формату графов~(\texttt{.dot}) и отсутствию внешних зависимостей, специфичных для окружения разработки. |
There was a problem hiding this comment.
через консольный сценарий
Это очень не по-русски
Проверка переносимости показала
Переносимости кого (всего UCFS?), куда? (Я ничего не понял)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.