diff --git a/doc/tutorial/images/changelog.png b/doc/tutorial/images/changelog.png new file mode 100644 index 0000000..bd8898b Binary files /dev/null and b/doc/tutorial/images/changelog.png differ diff --git a/doc/tutorial/images/oops.png b/doc/tutorial/images/oops.png new file mode 100644 index 0000000..dd541c7 Binary files /dev/null and b/doc/tutorial/images/oops.png differ diff --git a/doc/tutorial/images/resources.png b/doc/tutorial/images/resources.png new file mode 100644 index 0000000..dede54b Binary files /dev/null and b/doc/tutorial/images/resources.png differ diff --git a/doc/tutorial/images/webvowl.png b/doc/tutorial/images/webvowl.png new file mode 100644 index 0000000..3c6bfc3 Binary files /dev/null and b/doc/tutorial/images/webvowl.png differ diff --git a/doc/tutorial/index.html b/doc/tutorial/index.html index 9b5a58a..79e5832 100644 --- a/doc/tutorial/index.html +++ b/doc/tutorial/index.html @@ -170,7 +170,7 @@

4 After clicking on "Next", you will see the final configuration window for WIDOCO:

-
+
@@ -183,35 +183,90 @@

4.1 Selecting Documentation Sections

You can configure which sections you want to include in your document by clicking on the check boxes shown in the figure above (red number 1). You may also load your own HTML if you prefer, by clicking on the "Load..." button that appears next to each section. Don't worry about the styles! Everything will be formatted with a consistent layout.

- The sections to include (abstract, introduction, overview, description and references) will include a placeholder text that you can later edit easily. The "Include annotation properties" option, however, will search your ontology for any metadata annotation properties that may have been defined; and the "include named individuals" option will list in the documentation any named individual found. This is particularly useful when you have a few individuals as examples of your ontology terms. However, we discourage choosing this option when a high number of individuals is present in the ontology, as the resultant HTML would be too big. + The sections to include (abstract, introduction, overview, description and references) will include a placeholder text that you can later edit easily. The "Include annotation properties" option, however, will search your ontology for any metadata annotation properties that may have been defined; and the "include named individuals" option will list in the documentation any named individual found. This is particularly useful when you have a few individuals as examples of your ontology terms. However, I discourage choosing this option when a high number of individuals is present in the ontology, as the resultant HTML would be too big.

4.2 Documentation Provenance

- Provenance is a record of how things have changed. When this option is selected, WIDOCO lists who have been responsible for the creation of the documentation of your ontology (together with a few other details such as the license, creation date, etc.). By default, WIDOCO will take the authors and contributors of the ontology as responsible agents for the document. An additional document with an RDF representation of the provenance record will also be exported. + Provenance is a record of how a resource was produced. When you select this option in the interface, WIDOCO lists who have been responsible for the creation of the documentation of your ontology (together with a few other details such as the license, creation date, etc.). By default, WIDOCO will take the authors and contributors of the ontology as responsible agents for the document. An additional document with an RDF representation of the provenance record will also be exported.

4.3 Content Negotiation

- If you plan to publish an ontology in your own server, you should select the option "Create an .htaccess file". Content negotiation enables serving multiple serializations of a resource depending of what a user requests. For example, imagine that you want to access the documentation of your ontology from a browser. Since you are a human, you are expecting to see something that you can read about your ontology. However, if you are a computer program you may want the RDF/XML representation of the ontology, or maybe a JSON-LD one. + If you plan to publish an ontology in your own server, you should select the "Create an .htaccess file" option. Content negotiation enables serving multiple serializations of a resource (in this case, your ontology) depending of what is requested. For example, imagine that you want to access the documentation of your ontology from a browser. Since you are a person, you are expecting to see something that you can read about your ontology, like the HTML documentation. However, if the request is issued by a program, such as Protégé, a machine readable representation like RDF/XML or JSON-LD will be preferred. +

+

+ WIDOCO follows the W3C Best practices for publishing RDF vocabularies, and will prepare the .htaccess file assuming that the current project folder will be deployed on the root folder of your server. However, you can edit the base path by clicking on the "Set base path" option. For more information on how to prepare .htaccess files and their rules for serving content, I recommend having a look at the Apache mod rewrite documentation.

4.4 Visualization

-

+

+ WIDOCO is integrated with WebVowl, a program designed to visualize ontologies. By selecting the option "Add link to WebVowl visualization", WIDOCO will generate and save a diagram of your ontology. An example can be seen in the figure below +

+
+ +

4.5 Generating an automated Changelog

-

Note here that you have to add a previous version or else it won't work

+

If you select the "Include a change log from last version", WIDOCO will generate a section at the end of the document describing the differences between the current version and the previous one. In order for WIDOCO to be able to generate this changelog, the previous version has to be annotated in the ontology metadata using any of the properties listed on the best practices document (for example, owl:priorVersion).

+ +

WIDOCO extends Bubastis, a software generated for creating ontology differences in a human readable manner. An example of a resulting changelog can be seen below:

+ +
+ +
+

4.6 Changing default documentation style

-

+

+ You can customize the style in which WIDOCO displays the documentation by editing the CSS included in the main folder. However, one of WIDOCO's users contributed a new stylem used in the BNE ontology. If you like it, just select the "Custom" style option. +

4.7 Documentation Analytics

-

+

+ Google analytics is used by many researchers and institutions to measure who accesses your web pages. If you have a code for tracking your website, WIDOCO will include a javascript snippet in the documentation to start tracking your ontology traffic. +

-

5. View, Explore and Evaluate your Ontology Documentation

-

5.1 Evaluating your ontology

-

+

5. View, Explore and Evaluate your Documentation

+

+ After clicking "Generate!" on the previous step, you will see the following image: +

+ +
+ +
+

+ Congratulations! Your documentation has been successfully generated. If you click on "View the ontology documentation in your web browser" (number 1 in red in the figure), the resultant documentation will be opened in a new window. If you use Chrome, you may not see the sections of the document. Don't panic! Sometimes when browsing your ontology in your local computer, the browser deactivates loading local content. You may use another browser to see the content locally, or adopt any of the solutions listed on the WIDOCO readme file. In any case, there should not be an issue when serving the contents from a server. +

+ +

5.1 Creating an evaluation of your ontology

+

+ Now that you are done with the documentation, you may get an OOPS! evaluation report by clicking "Validate your ontology with OOPS!" (number 2 in red in the figure above). The report will show potential design pitfalls of your ontology and will be saved in the project folder as an HTML file. If no pitfalls are found, OOPS! will return a page similar to the image below: +

+ +
+ +

5.2 Exploring generated resources

-

+

+ After generating your ontology documentation, your project folder will look very similar to the following image: +

+
+ +
+ +

Here is a description of each of them:

+

6. WIDOCO through command line

-

+

+ WIDOCO can be executed from the command line in case you want to set it up in an automated manner in your workflow. All the flags that may be used for configuration (which are the same as the features descibed in this document) can be seen in detail in the "How to use WIDOCO" section of the readme file in the GitHub repository. +

This tutorial has been written by Daniel Garijo. diff --git a/src/main/java/widoco/gui/TestStep0.form b/src/main/java/widoco/gui/TestStep0.form new file mode 100644 index 0000000..eeb0030 --- /dev/null +++ b/src/main/java/widoco/gui/TestStep0.form @@ -0,0 +1,262 @@ + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +