Difference between revisions of "Lazarus Documentation Editor/ru"

From Free Pascal wiki
Jump to navigationJump to search
(Deleted English category)
 
(8 intermediate revisions by one other user not shown)
Line 62: Line 62:
 
И, наконец, показывается описание. Это текст, введенный в поле description lazde.
 
И, наконец, показывается описание. Это текст, введенный в поле description lazde.
  
−
== Adding documentation for new units ==
+
== Добавление документации для новых модулей ==
  
−
There are of course many other units waiting to be documented. If the unit is part of a package, it is likely that there is no xml file for you to start from. You will then have to start from scratch, and lazde has a function to get you off to a flying start. Just go to File -> New and the following screen appears:
+
Конечно, есть много других модулей, ожидающих документирования. Если модуль является частью пакета, скорее всего, для вас не существует xml-файла, с которого вы можете начать документирование. Вам придется начинать с нуля, и у lazde есть функция, которая поможет вам сделать это. Просто зайдите в File -> New и появится следующее окно:
−
<center>[[Image:Lazdenewdocfromfile.png]]</center>
 
−
You start by naming the package. All units you want to add to this package should be given the same package name. Afterwards you enter the source file to use. You can browse to this file as well. Then enter a name for the output file - do not forget the xml extension! - and click OK.
 
  
−
lazde will then generate the skeleton documentation. The generated file will be opened and the treeview will be populated with all the units, classes, types, functions and so on from your source file. Now you are ready to start documenting a new part of Lazarus.
+
[[Image:Lazdenewdocfromfile.png]]
  
−
Have a look at [[LCL Documentation Roadmap]] to see which units still need to be documented.
+
Вы начнете процесс написания документации, дав имя пакету. Все модули, которые вы хотите добавить в этот пакет, должны иметь одинаковое имя. После этого в поле "Input file" вы вводите исходный файл для использования. Вы также можете просмотреть этот файл. Затем введите в поле "Output file" имя для выходного файла - не забудьте про расширение xml! - и нажмите ОК.
  
−
You can use [[FPDoc Updater]] to easily update FPDoc files when Pascal units have been changed.
+
Затем lazde сгенерирует скелет документации. Сгенерированный файл будет открыт, а древовидная структура будет заполнена всеми модулями, классами, типами, функциями и т.д. из исходного файла. Теперь вы готовы начать документировать новую часть Lazarus.
  
−
== The Final result ==
+
Взгляните на [[LCL Documentation Roadmap|дорожную карту документации LCL]], чтобы увидеть, какие модули еще нуждаются в документировании.
  
−
What I experienced during the use of the program is that I would like to see how the information is shown in its final stage (as a browsable document). For this purpose lazde makes use of a utility to build all necessary HTML-files.
+
Вы можете использовать [[FPDoc Updater]], чтобы легко обновлять файлы FPDoc, когда модули Pascal были изменены.
  
−
This utility can be started from the menu Extra -> Build. The following screen will be shown:
+
== Окончательный результат ==
−
<center>[[Image:Lazdebuild1.png]]</center>
+
 
−
"Package" should be the same as the name you gave when you created the xml files. For "Format" choose HTML. At "Output" you enter the path where the resulting files should be placed.
+
Что я испытывал во время использования программы, так это то, что мне хотелось бы увидеть, как информация отображается на ее заключительном этапе (в виде просматриваемого документа). Для этого lazde использует утилиту для сборки всех необходимых HTML-файлов.
−
Press "Add all" and all documents your were working on will be added to the project. Then go to the next to tab
+
 
−
<center>[[Image:Lazdebuild2.png]]</center>
+
Эта утилита может быть запущена из меню Extra -> Build. На следующем скрине будет показано:
−
and enter the paths to the source files.
+
 
−
After you have pressed build your HD will start to rattle and finally the following output will be shown on the "Build output" tab.
+
[[Image:Lazdebuild1.png]]
 +
 
 +
"Package" должен совпадать с именем, которое вы дали при создании XML-файлов. Для "Format" выберите HTML. В поле "Output" вы вводите путь, в котором должны быть размещены полученные файлы.
 +
Нажмите "Add all" (Добавить все), и все документы, над которыми вы работали, будут добавлены в проект. Затем перейдите к следующей вкладке
 +
 
 +
[[Image:Lazdebuild2.png]]
 +
 
 +
и введите пути к исходным файлам.
 +
После того, как вы нажали build, ваш HD начнет тарахтеть и, наконец, на вкладке «Build output» будет показан следующий вывод.
 +
 
 +
<syntaxhighlight lang=bash>
 
  Building docs using command: fpdoc --package="LCL"
 
  Building docs using command: fpdoc --package="LCL"
 
  --output="/home/matthijs/documentatie/LCL" --format=html --content  
 
  --output="/home/matthijs/documentatie/LCL" --format=html --content  
Line 95: Line 103:
 
  --input="/home/matthijs/cvsroot/lazarus/lcl/dialogs.pp"
 
  --input="/home/matthijs/cvsroot/lazarus/lcl/dialogs.pp"
 
  --input="/home/matthijs/cvsroot/lazarus/lcl/controls.pp"  
 
  --input="/home/matthijs/cvsroot/lazarus/lcl/controls.pp"  
−
+
 
 
  FPDoc - Free Pascal Documentation Tool
 
  FPDoc - Free Pascal Documentation Tool
 
  (c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org
 
  (c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org
Line 102: Line 110:
 
  Done.
 
  Done.
 
  Documentation successfully built.
 
  Documentation successfully built.
 +
</syntaxhighlight>
  
−
When you go to the directory you entered at "Output" you will see a index.html file and (in this case 4) sub directories. Open index.html in your favorit browser and see the result of all your hard work on the documentation. You will be able to follow the links and read it all.
+
Когда вы перейдете в каталог, который вы ввели в поле "Output", вы увидите файл index.html и подкаталоги (в данном случае 4 шт.). Откройте index.html в вашем любимом браузере и посмотрите результат всей вашей тяжелой работы над документацией. Вы сможете перейти по ссылкам и прочитать все это.
−
 
 
−
When you plan to continue working on this package of documentation, press "Save" and save the build options. You will be asked to provide a name for the file and the options will be saved. Next time you want to build the HTML-files you can just "load" them again.
 
  
−
== Submitting your work ==
+
Если вы планируете продолжить работу с этим пакетом документации, нажмите "Save" (Сохранить) и сохраните параметры сборки. Вам будет предложено указать имя файла, и параметры будут сохранены. В следующий раз, когда вы захотите собрать HTML-файлы, вы можете просто «загрузить» их снова.
−
When you are satisfied with your work on Lazarus' documentation, you certainly want to share it with the Lazarus community. All you have to do is make a [[Creating A Patch|patch]], zip the patch and send it in.
 
  
−
== Improvements welcome ==
+
== Отправка ваших трудов ==
−
{{Note| lazde is a work-in-progress. It does work, but it's certainly not completely finished yet. You may encounter bugs. Feel free to fix them!}}
+
Если вы довольны своей работой над документацией Lazarus, вы наверняка захотите поделиться ею с сообществом Lazarus. Все, что вам нужно сделать, это создать [[Creating_A_Patch/ru|патч]], заархивировать и отправить его.
  
−
[[Category:Applications created with Lazarus]]
+
== Улучшения приветствуются ==
 +
{{Note| lazde находится в стадии разработки. Он работает, хотя, конечно, еще не полностью закончен. Вы можете столкнуться с ошибками. Не стесняйтесь исправлять их!}}

Latest revision as of 15:43, 24 July 2020

│ Deutsch (de) │ English (en) │ español (es) │ français (fr) │ 日本語 (ja) │ polski (pl) │ русский (ru) │ slovenčina (sk) │

Введение

Хорошая, исчерпывающая документация является важной недостающей частью Lazarus. Чтобы помочь подготовить необходимую документацию, был разработан инструмент под названием LazDE. На этой странице описывается использование этого инструмента для редактирования существующей документации или для создания новых файлов документации. В этом вики-документе я использую [$LazDir] для обозначения базового каталога Lazarus. Поэтому, когда вы читаете [$LazDir], просто замените его на каталог, соответствующий вашей установке Lazarus.

Обоснование

Основная цель этого проекта документации - сделать доступным онлайн-файл справки. Чтобы сделать файл справки независимым от платформы, мы используем файлы XML для записи и хранения данных документации. Каждый модуль Lazarus имеет свой собственный файл данных XML-документации.

Большое количество таких файлов XML уже написано, и их можно использовать:

  • для создания HTML-страниц, к которым вы можете получить доступ на https://lazarus-ccr.sourceforge.io/docs/lcl/
  • для создания CHM-файлов, которые можно просматривать в автономном режиме (после помещения в правильно зарегистрированный локальный каталог) в качестве справки для Lazarus, которая доступна даже в том случае, если у вас нет доступа к Интернету.

Задача документирования Lazarus выполняется

Как упоминалось выше, XML был выбран в качестве формата данных документации, поскольку он не зависит от платформы. Текущую документацию можно найти в [$LazDir]/docs/xml/. Пока что каталог /lcl/ содержит в основном пустые файлы скелетов, которые содержат мало (или не содержат) полезной документации. XML-файлы, которые вы найдете в этом каталоге, генерируются автоматически и должны быть адаптированы, чтобы быть полезными. Итак, теперь мы знаем, где найти файлы, давайте посмотрим на инструмент, который мы разрабатываем для создания и адаптации файлов данных документации.

Инструмент документирования Lazarus

"Lazde" - это инструмент, предназначенный для редактирования файлов документации XML. Его также можно использовать для генерации базового скелета XML-файла, полученного из исходного файла модуля Pascal, и (с помощью внешнего инструмента FPDoc) для генерации HTML-версии документации. Пример вывода FPDoc можно увидеть здесь, часть документации на данный момент. Поскольку скомпилированные исполняемые версии lazde не поставляются, вы должны самостоятельно создать один экземпляр для себя. Исходники "lazde" можно найти в [$LazDir]/doceditor/. Когда вы соберете и запустите эту программу, если вы откроете [$LazDir]/docs/xml/lcl/dialogs.xml, вы увидите такую картинку

Lazdemain.png

Документирование LCL

Lazdeelements.png

Открытие узла "Packages"(пакеты) показывает узел "LCL", который содержит узел "Dialogs"(диалоги). Выбор этого последнего узла заполняет нижнюю TreeView с элементами. Эти элементы списка Constants (константы), Types (типы) and Classes (классы) определены в модуле Dialogs.pp. Любые модули, используемые dialogs.pp также добавляются в качестве дополнительных узлов. Другие узлы добавляются для свойств класса, параметров функций и процедур, и так далее.

Выбор узла в нижнем левом дереве отображает содержимое этого узла с правой стороны окна.

Если взглянуть на эту страницу, вы увидите обзор классов, определенных в модуле "dialogs". Напротив названия каждого класса вы увидите строку текста-пояснения, который был введен в «короткий» EditBox редактора lazde.

Далее под «коротким» EditBox будет подразумеваться поле для заметок, куда вы можете вводить более подробное описание компонента или свойства.

Light bulb  Примечание: Если вы хотите вставить новую строку, используйте тэг <br/>

Below the main description field are further fields labelled "Errors", "See also" and "Example code File". Ниже основного описания поля есть дополнительными поля, обозначенные как "Errors" (ошибки), "See also" (см. также) и "Example code File" (файл с кодом примера).

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

Каждое поле - "See also" (см. также) и "Example code File" (файл с кодом примера) - снабжено тремя кнопками (+, ^, -). Эти кнопки позволяют добавлять и удалять ссылки на другие страницы или примеры кода соответственно.

Результат

Посмотрите на описание InputQuery. В верхней части страницы вы можете увидеть, о чем эта страница (в нашем случае о функции InputQuery из dialogs.pp). Первая строка текста содержит то, что было введено в «коротком» EditBox в lazde.

Далее следует объявление этой функции, взятое из исходного файла dialogs.pp. Часть объявления создается html-компоновщиком и анализируется непосредственно из исходников. Поскольку есть две версии этой функции, исходная позиция говорит 0.

Прим.перев.: на момент перевода статьи по указанной ссылке видны три функции с Source position: dialogs.pp line 761.

Затем приводятся аргументы. Когда вы откроете узел InputQuery в lazde, вы увидите каждый аргумент отдельно как дочерний узел. Текст, показанный после каждого аргумента, соответствует тому, что было введено в "Короткий" editbox , когда был выбран соответствующий дочерний узел.

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

И, наконец, показывается описание. Это текст, введенный в поле description lazde.

Добавление документации для новых модулей

Конечно, есть много других модулей, ожидающих документирования. Если модуль является частью пакета, скорее всего, для вас не существует xml-файла, с которого вы можете начать документирование. Вам придется начинать с нуля, и у lazde есть функция, которая поможет вам сделать это. Просто зайдите в File -> New и появится следующее окно:

Lazdenewdocfromfile.png

Вы начнете процесс написания документации, дав имя пакету. Все модули, которые вы хотите добавить в этот пакет, должны иметь одинаковое имя. После этого в поле "Input file" вы вводите исходный файл для использования. Вы также можете просмотреть этот файл. Затем введите в поле "Output file" имя для выходного файла - не забудьте про расширение xml! - и нажмите ОК.

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

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

Вы можете использовать FPDoc Updater, чтобы легко обновлять файлы FPDoc, когда модули Pascal были изменены.

Окончательный результат

Что я испытывал во время использования программы, так это то, что мне хотелось бы увидеть, как информация отображается на ее заключительном этапе (в виде просматриваемого документа). Для этого lazde использует утилиту для сборки всех необходимых HTML-файлов.

Эта утилита может быть запущена из меню Extra -> Build. На следующем скрине будет показано:

Lazdebuild1.png

"Package" должен совпадать с именем, которое вы дали при создании XML-файлов. Для "Format" выберите HTML. В поле "Output" вы вводите путь, в котором должны быть размещены полученные файлы. Нажмите "Add all" (Добавить все), и все документы, над которыми вы работали, будут добавлены в проект. Затем перейдите к следующей вкладке

Lazdebuild2.png

и введите пути к исходным файлам. После того, как вы нажали build, ваш HD начнет тарахтеть и, наконец, на вкладке «Build output» будет показан следующий вывод. 

 Building docs using command: fpdoc --package="LCL"
 --output="/home/matthijs/documentatie/LCL" --format=html --content 
 --descr="/home/matthijs/Projecten/Lazarus/doceditor/buttons.xml"
 --descr="/home/matthijs/Projecten/Lazarus/doceditor/comctrls.xml"
 --descr="/home/matthijs/Projecten/Lazarus/doceditor/dialogs.xml"
 --descr="/home/matthijs/Projecten/Lazarus/doceditor/controls.xml"
 --input="/home/matthijs/cvsroot/lazarus/lcl/buttons.pp"
 --input="/home/matthijs/cvsroot/lazarus/lcl/comctrls.pp"
 --input="/home/matthijs/cvsroot/lazarus/lcl/dialogs.pp"
 --input="/home/matthijs/cvsroot/lazarus/lcl/controls.pp" 

 FPDoc - Free Pascal Documentation Tool
 (c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org
 
 Writing 2788 pages...
 Done.
 Documentation successfully built.

Когда вы перейдете в каталог, который вы ввели в поле "Output", вы увидите файл index.html и подкаталоги (в данном случае 4 шт.). Откройте index.html в вашем любимом браузере и посмотрите результат всей вашей тяжелой работы над документацией. Вы сможете перейти по ссылкам и прочитать все это.

Если вы планируете продолжить работу с этим пакетом документации, нажмите "Save" (Сохранить) и сохраните параметры сборки. Вам будет предложено указать имя файла, и параметры будут сохранены. В следующий раз, когда вы захотите собрать HTML-файлы, вы можете просто «загрузить» их снова.

Отправка ваших трудов

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

Улучшения приветствуются

Light bulb  Примечание: lazde находится в стадии разработки. Он работает, хотя, конечно, еще не полностью закончен. Вы можете столкнуться с ошибками. Не стесняйтесь исправлять их!
Retrieved from "http://wiki.freepascal.org/index.php?title=Lazarus_Documentation_Editor/ru&oldid=138036"