Диссертация (1149623), страница 7
Текст из файла (страница 7)
Knuth) [92]. ТеХ позволяет добиваться типографскогокачества вёрстки с использованием персональных компьютеров. Базовые возможности языка ТеХ ориентированы на управление деталями внешнего видатекста. Система LaTeX [93], созданная Л. Лампортом (L. Lamport) и являющаясядальнейшим развитием ТеХ, делает акцент на возможностях семантической разметки текста, предлагает для разработки документов классы и стилевые пакеты.TeX и LaTeX поддерживают повторное использование при помощи макроопределений и конструкций условного включения.
Например, при использованииэтих инструментов для написания диссертации авторы часто вставляют часть автореферата также и во введение основного текста диссертации. Но при этом требуется дополнительно отобразить ссылки на соответствующую литературу, которые, как правило, отсутствуют в автореферате в виду ограничений на егообъём. Для этого повторно используемая часть автореферата оформляется отдельно и содержит в себе условные включения этих ссылок.
Далее в каждом издвух текстов, в которые общая часть включается с помощью директивы «\input»,Стандартный механизм включения содержимого одного XML-файла на место тега директивы «<include>» в другом.1030определяется своё значение переменной условного включения, и ссылки появляются или нет в тексте в зависимости от значения этой переменной. Аналогичныеспособ используется и при написании разных версий одной и той же научнойстатьи.В настоящее время активно развиваются легковесные языки разметки, которые проще в освоении, чем LaTeX, DocBook, DITA.
В качестве примеров такихязыков можно привести языки форматирования Вики-страниц WikiWiki [53],MediaWiki [39], а также универсальные языки разметки ReStructuredText [104],AsciiDoc [22], Markdown [96]. В последнее время некоторые проекты по разработке ПО, ранее использовавшие DocBook, отказываются от него в пользу такихязыков [51, 108, 152]. Форматирование текстов с помощью легковесных языкахосуществляется посредством отступов, пропусков строк и простейшей псевдографики, например, символов «*» и «-» для маркированных списков, «подчёркивания» заголовков при помощи символа «=» и т.д.
Многие легковесные языкитакже поддерживают Single Source с генерацией различных конечных представлений (Microsoft Word, HTML, LaTeX, PDF, EPub и т.д.) при помощи таких систем как Pandoc [113] и GitBook [69].Повторное использование поддерживается Wiki-языками при помощи специальных директив, позволяющих включать в Wiki-страницу отдельно описанныефрагменты текста. Универсальные легковесные языки не предоставляют стандартных возможностей повторного использования.Известным примером системы генерации документации ПО по исходным текстам является Javadoc [84].
Для осуществления генерации требуется наличиеспециальных комментариев в Java-коде. Эти комментарии могут содержать директивы для обозначения различных конструкций языка Java — параметровфункций, констант и т.д. Основной выходной формат для Javadoc — HTML, носуществует возможность подключать внешние модули для генерации RTF и некоторых других форматов. Javadoc не предоставляет возможностей повторногоиспользования. Аналогичные средства генерации документации имеются на31платформах Microsoft .NET и Python, а также во многих других современных средах программирования. Следует отметить, что существуют подобные средства,которые обеспечивают работу с различными языками программирования.Например, система Doxygen [61] поддерживает C/C++, D, Fortran, Perl, Tcl и выходные форматы HTML, Microsoft HELP, RTF, LaTeX, ROFF.
Doxygen ограниченно поддерживает повторное использование, позволяя при помощи специальных директив включать в выходное представление документации примеры исходного кода.Сводная информация об описанных выше языках разметки текстов представлена в табл. 1.4.1.Табл. 1.4.1. Свойства языков разметки текстовНазваниеRUNOFF, *ROFFГодпоявленияSingleSourceWYSIПовторноеWYM использование≥1964 Ограничено НетНетSGML1974 НетНетНетDocBook1994 ДаДаОграниченоDITA2001 ДаДаДаDRL2008 ДаДаДаTeX1978 НетНетДаLaTeX1985 НетДаДа≥1995 НетДаОграниченоЛегковесные языкиобщего назначения2002 ДаДаНетJavadoc1995 Ограничено НетНетDoxygen1997 ДаОграниченоWiki (различные)НетСледует отметить, что современные средства разработки документации ПО(языки и программные средства) поддерживают повторное использование32крайне незначительно [112], и сама эта практика не является пока общеупотребимой.
В этом направлении требуются дополнительные усилия исследователей,разработчиков языков и инструментов.1.5. О размере документации ПОВажным вопросом при выборе методов и средств поиска является оценка данных, на которых происходит поиск. В связи с этим было выбрано 19 документовПО из различных проектов: 12 документов были взяты из известных открытыхпроектов (open source projects), 7 — из коммерческих проектов. Полный списокдокументов представлен в табл. 1.5.1.33Табл. 1.5.1.
Документация ПО, выбранная для экспериментов№ДокументDocBook definitive1 guide2 Subversion Book34567891011Zend Framework V1guideLinux KernelDocumentationGNU Core UtilsManualPostgre SQL ManualThe GIMP user manualBlender referencemanualLibLDAP ManualEclipse SWTReferencePython Requests12 Qt Quick Reference13 Документ 114 Документ 215 Документ 316 Документ 417 Документ 518 Документ 619 Документ 7Тип документаДоступСправочник по языкуРук-во по администрированиюhttp://docbook.org/https://subversion.apache.org/https://github.com/zendframework/zf1/tree/master/doРук-во программиста cumentationhttps://github.com/torvaldsРук-во программиста /linux/tree/master/kernelhttps://www.gnu.org/softwРук-во пользователяare/coreutils/coreutils.htmlСправочник по языку https://www.postgresql.orgРук-во пользователяhttps://www.gimp.org/Рук-во пользователяAPI-документацияhttps://www.blender.org/http://www.openldap.org/API-документацияAPI-документацияhttp://git.eclipse.org/http://python-requests.org/http://wiki.qt.io/Developer_Guides-Рук-во программистаРук-во пользователяРук-во пользователяСпецификация требованийСпецификация архитектурыСпецификация требованийСпецификация архитектурыСпецификация требований-Говорить об объёме документации ПО сложно потому, что она разрабатывается и существует в различных форматах, состоит из многочисленных файлов.Был выбран следующий способ оценки объёма документов.
Файлы, относящиеся34к одному документу, были объединены в один, и после этого при помощи утилиты Pandoc [113] получившийся файл конвертировался в «плоский» текст —неразмеченный текст в кодировке UTF-8. Таким образом, из этих итоговых документов была устранена вся разметка, картинки и прочая дополнительная информация.Размер документа определялся как размер такого файла. Среднийразмер одного документа из табл. 1.5.1 составил 757 Кб, максимальный размер — 2512 Кб.
Для того, чтобы нагляднее представить, насколько велики этидокументы, автор диссертационного исследования конвертировал те же исходные файлы утилитой Pandoc в формат Microsoft Word (шрифт Times New Roman,кегль 11, одинарный интервал, страница A4). Как можно увидеть в табл. 1.5.2,размер нескольких документов оказался близок к 1000 страницам, размер одиндокумента превысил 1000 страниц. Автор диссертационного исследования склонен считать, что в области разработки ПО не встречается существенно бо́льшихдокументов.
В связи с этим можно положить допустимый верхний предел размеров одного документа в 3 Мб «плоского» текста. В основном, предложенный вработе Duplicate Finder работает именно с «плоским» текстом. Имеются такжевозможности для работы с DocBook-документами, которые, как следует изтабл. 1.5.2, могут быть ненамного больше и тоже укладываются в ограничение 3Мб. Можно предположить, что остальные существующие документы будутблизки по размерам к тем, которые были выбраны, так как были рассмотреныдостаточно крупные проекты11.Далее в этом исследовании для экспериментов будет использована именно этавыборка документов.Следует отметить, что в целом документация по проекту может быть объёмнее, однако вданном исследовании не рассматривается вся документация проекта, а только отдельные документы, которые, однако, могут быть представлены набором исходных файлов.1135«Плоский»текст, Кб704185422263271182515232483332129429951861668689514739183328269296599180316911 10559372104105616965824939153160566660673915453198110411611833 12256 501138360925121076432111222158320 1168145489491449363421342 2241110170734317343 7343107176250512505 2505581001641164164209717874447 1787105241138111381 1381224381718178172050768176876863167757Кол-вофайловСр.
размерфайла, КбРазмер,КбДокументФорматDocBook definitive1guideDocBook2 Subversion Book DocBookZend Framework3V1 guideDocBookLinux Kernel4DocumentationDocBookGNU Core Utils5ManualTROFFPostgre SQL6ManualTROFFThe GIMP user7manualDocBookBlender reference ReStructure8manualdText9 LibLDAP Manual TROFFEclipse SWT10ReferenceJava11 Python Requests PythonQt Quick12ReferenceEPubMicrosoft13 Документ 1WordMicrosoft14 Документ 2WordMicrosoft15 Документ 3WordMicrosoft16 Документ 4WordMicrosoft17 Документ 5WordMicrosoft18 Документ 6WordMicrosoft19 Документ 7WordСреднееРазмер,Кб№Кол-востраницТабл.
1.5.2. Объём выбранной документации ПОФорматИсходная документацияMS Word361.6. Используемые в диссертации методы, модели и технологииВ данном разделе описываются методы и технологии, использованные в данной диссертации.Технология DocLine и рефакторинг документацииСистема DocLine и язык DRL [11, 21] предназначены для планового повторного использования документации на DocBook. DocLine/DRL позволяет применить подход адаптивного повторного использования, предложенный С. Ерзабеком (S. Jarzabek) и П. Бассеттом [83], к разработке документации ПО.Язык DRL расширяет набор тегов DocBook новыми тегами, которые позволяют определять повторно используемые фрагменты текста (информационныеэлементы или словари). Документация в формате DRL обрабатывается препроцессором, который раскрывает ссылки и выдаёт документ в формате DocBook.Дальнейшая обработка DocBook-документации может выполняться стандартными для DocBook средствами с генерацией PDF, HTML, RTF и т.д.Рассмотрим пример повторного использования фрагментов текста средствамиDocLine.
Пусть в тексте документа имеется два схожих фрагмента, представленные на листинге 1.6.1 (здесь жирным выделены отличия этих фрагментов):…When module instance receives refresh_news call, it updates its data from RSS andAtom feeds it is configured to listen to and pushes new aticles to the main storage.…When module instance receives refresh_news call, it updates its data from Twitter feedsit is subscribed to and pushes new articles to the main storage.…Листинг 1.6.1.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
