diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..ba65b13 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8d0ff1b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,50 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# + + +# -- Project information ----------------------------------------------------- + +project = 'LIDIA' +copyright = '2023' +author = 'Utrecht University' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/extension.rst b/docs/extension.rst new file mode 100644 index 0000000..d9cbdcf --- /dev/null +++ b/docs/extension.rst @@ -0,0 +1,184 @@ + +The LIDIA Zotero extension +========================== + +.. note:: + This part of the manual is updated for version 0.3.0 of the extension. + + +Installing the extension +------------------------ +The extension consists of the file ``lidia-annotations_v*.*.*.xpi`` and +works together with version 6 of the Zotero desktop application +on all operating systems that Zotero supports (Windows, macOS and Linux). +It is not possible to run the extension using the browser version of Zotero. + +After downloading the file, click **Options** → **Add-ons**, click the +option button in the upper-right corner of the window and click +**Install Add-on From File**. After selecting the extension file the +extension will be activated. + +.. note:: + The extension should work immediately after activating it. If this is + not the case, try restarting Zotero. + +Activating synchronization with the LIDIA Zotero group +------------------------------------------------------ +.. note:: + If you are not able to join the LIDIA group at this moment, it is possible + to postpone this step and start annotating right away. You can add your + annotated documents to the group afterwards. + +The LIDIA annotations are saved and synchronized in a Zotero group that has +been set up for this purpose. This makes it possible to collaborate with +others on the same documents. Annotated documents inside the group will +automatically become visible on the LIDIA website (or at least, that is the +plan!). + +The Zotero group is a private group and you should request an invitation +to join it. Once you receive the invitation, you can join the group using +the link you receive by e-mail. + +To contribute to the group, it is necessary to enable synchronization with your +Zotero account. For this, click **Edit** → **Preferences** and enter your +username and password. If necessary, there is a link to create an account. +After joining the group and enabling synchronization, the group will be +visible in Zotero as a folder and any document and attached file you add +to this folder will be part of the group library. + +Annotating a document +--------------------- +To start annotating, first make sure that you have a bibliographical +Zotero item (e.g. a book, a chapter of a book or an article in a journal) +with an attached PDF file. You can create the bibliographical item in the +usual way using the various options that Zotero supports. You can upload +the PDF then from your own computer by right-clicking and selecting +**Add attachment** → **Add copy of file**. +At this stage, you can choose whether you +want to work with the document inside your own library or in the shared +LIDIA library, because you can move items including your annotations around +without problems. + +.. note:: + Zotero allows you to work with a link to a local PDF file as an alternative + to importing the PDF to your Zotero library. This will work, but it will + not be possible to add the file with its annotation to a shared group + in this case. Working with links to online PDF files is not possible because + these will always be opened externally. + +Next, open the PDF file by double-clicking it. The PDF will open inside +the Zotero window. You will then need to open the two sidebars on the left +and right hands of the window by clicking the leftmost button and the button +second from the right on the toolbar. + +You can create an annotation by selecting a piece of text and selecting a +colour to mark the text with. The colour you choose is ignored by LIDIA. +The annotation will immediately be visible in the overview of annotations +in the sidebar on the left. Click the new annotation, and in the sidebar +on the right you will see editable fields in the LIDIA toolbar. You can +now fill in the fields and click **Save** to save your annotation. If you +have activated synchronization with your Zotero account, your annotation +will immediately be saved online in your account as well. If you have put +the document in the LIDIA Zotero group, it will also be visible for other +users of the group. + +Editing annotations +------------------- +Editing annotations works the same as creating new ones: click the annotation +in the sidebar on the left and start editing. + +If the annotation was created by another user in the same group, you can +view the annotation but you cannot edit it. + +You can only edit annotations that are new (i.e., they do not contain +a comment) or that were saved by the LIDIA extension. Existing annotations +can be converted to LIDIA extensions, however. + +.. note:: + It is not possible to edit annotations by selecting the annotations + from within the text -- you have to use the sidebar on the left. + +Annotations that run on multiple pages +-------------------------------------- +Zotero does not allow annotations that run over the borders of a single page. +It is possible to annotate text that covers multiple pages, but Zotero will +create multiple annotations for it automatically. To annotate an argument that +runs over multiple pages, do the following: + +* Create an annotation for all of the text. Zotero will automatically split + this up into one annotation per page. +* Select the first created annotation (on the first page of the text), fill + out the LIDIA form, and save the annotation +* Select the annotations on the subsequent pages one by one, select the + checkbox **Annotation is continuation of previous argument**, and save. You + will see that the rest of the form will be greyed out and that the information + that you just have filled in is shown. + +LIDIA does not support annotations that run across multiple non-continious +annotations. Instead, you may use the **Relation** field to indicate that +there are multiple annotations for one linguistic argument. + +Relations between annotations +----------------------------- +Use the **Relation** field to indicate that an annotation is somehow +related to a different annotation. The first box defines the +type of the relation, such as *Contradicts* and *Generalizes*. In the +second box you indicate to which annotation it is related. You can select from +all LIDIA annotations from the same Zotero library as that of the document +that you are currently working in. The references to the annotations +are shown using the title of the document and the name of the argument, +separated by a colon (:). + +Setting default values +---------------------- +It is possible to set default values for certain fields that are likely +to remain the same throughout a document. To do that, go to the library tab +(the leftmost tab), select the parent bibliographical item of the PDF file, +and go to the **Extra** field at the right side of the screen inside the +**Info** tab. This field is normally empty, but you can add LIDIA defaults to +it, such as: + +:: + + lidia.default_arglang: eng + lidia.default_termcategory: morphosyntax + +This will set the default argument language to English, and the default +lexicon term category to General. For ``lidia.default_arglang``, choose the +right ISO 639-3 language code (codes consisting of three characters, such as +``nld`` for Dutch). For ``lidia.default_termcategory``, choose from the +lexicon term categories that you find in the LIDIA form in the first combo box +of the **Lexicon term** field, but in lowercase and with spaces replaced by +dashes (such as ``part-of-speech``). + +Working with existing PDF annotations +------------------------------------- +PDF readers, such as Adobe Acrobat Reader, have their own annotation +capabilities. These annotations are saved as part of the PDF files. +Zotero, however, works with a different format for annotations where they +are not part of the PDF file but instead part of your Zotero library. +The advantage is that they can easily be shared with other people in +your Zotero group without uploading the full PDF time every time you make +a change. + +Zotero is capable of working with existing PDF annotations. To work with them +in LIDIA, however, you first have to convert them to Zotero annotations. +After importing the PDF in Zotero, open the PDF in the built-in reader +and click **File** → **Import Annotations**. Zotero will warn you that the +annotations will be removed from the PDF file and imported to your Zotero +library. That is because you would otherwise see a double set of annotations. +If you are working with local files, make sure you have a backup in case +of a failure during the import of the annotations. + +.. note:: + Apparently it is not possible to import PDF annotations in files that are + part of a shared Zotero group. If this is the case, first move the file + to your personal Zotero library, import the annotations and move the file + back to the group. + +Imported annotations will not be in the LIDIA format. You can convert them +by clicking an annotation and clicking the **Convert to LIDIA annotation** +button in the sidebar on the right side of the screen. LIDIA will then attempt +to read the existing annotation as a LIDIA annotation, with the text on the +first line as the annotation ID and the rest of the text as the description +of the argument. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..29c4b8b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +.. LIDIA handbook documentation master file, created by + sphinx-quickstart on Wed Mar 2 12:09:59 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to the LIDIA handbook! +============================== + +.. toctree:: + introduction + extension + :maxdepth: 2 + :caption: Contents + diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..2ae60a8 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,8 @@ +Introduction +============ + +.. note:: + + This chapter is not yet complete. + +LIDIA is a **L**\ inguistics **DIA**\ gnostics Database. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd