Skip to content

Commit

Permalink
docs: Fixed URLs and corrected typos (#10900)
Browse files Browse the repository at this point in the history
Removed backslashes that were causing errors in URLs.
  • Loading branch information
LoayGhreeb authored Feb 21, 2024
1 parent 4e9f49f commit 9e5e5a1
Show file tree
Hide file tree
Showing 8 changed files with 21 additions and 21 deletions.
2 changes: 1 addition & 1 deletion docs/code-howtos/IntelliJ.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ parent: Code Howtos
# IntelliJ Hints

{: .highlight }
Did you know that [IntelliJ allows for reformatting selected code](https://www.jetbrains.com/help/idea/reformat-and-rearrange-code.html#reformat\_code) if you press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>L</kbd>?
Did you know that [IntelliJ allows for reformatting selected code](https://www.jetbrains.com/help/idea/reformat-and-rearrange-code.html#reformat_code) if you press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>L</kbd>?

## Key hints for IntelliJ

Expand Down
2 changes: 1 addition & 1 deletion docs/code-howtos/javafx.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ parent: Code Howtos

## FXML

The following expressions can be used in FXML attributes, according to the [official documentation](https://docs.oracle.com/javase/8/javafx/api/javafx/fxml/doc-files/introduction\_to\_fxml.html#attributes)
The following expressions can be used in FXML attributes, according to the [official documentation](https://docs.oracle.com/javase/8/javafx/api/javafx/fxml/doc-files/introduction_to_fxml.html#attributes)

| Type | Expression | Value point to | Remark |
| -------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down
6 changes: 3 additions & 3 deletions docs/code-howtos/openoffice/ooresult-ooerror/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ grand_parent: Code Howtos

### Relieve GUI panel code

On the question of where should we catch exceptions in relation to GUI code it was suggested (Jonatan Asketorp [here](https://github.com/koppor/jabref/pull/496#discussion\_r629695493), "most of them (all?) should be handled latest in the ViewModel.") that catching them early could help simplifying the higher levels.
On the question of where should we catch exceptions in relation to GUI code it was suggested (Jonatan Asketorp [here](https://github.com/koppor/jabref/pull/496#discussion_r629695493), "most of them (all?) should be handled latest in the ViewModel.") that catching them early could help simplifying the higher levels.

### Same messages in different contexts

Expand All @@ -34,7 +34,7 @@ To avoid `OOBibBase` depending on the higher level `OpenOfficePanel` message tex
* Static constructors in `OOError` provide uniform translation from some exception types to `OOError` with the corresponding localized messages:\
`public static OOError from(SomeException ex)`\
There is also `public static OOError fromMisc(Exception ex)` for exception types not handled individually. (It has a different name, to avoid ambiguity)
* Another set of contructors provide messages for some preconditions.\
* Another set of constructors provide messages for some preconditions.\
For example `public static OOError noDataBaseIsOpenForCiting()`

Some questions:
Expand Down Expand Up @@ -62,7 +62,7 @@ During precondition checking
2. we may need to get some resources that might not be available (for example: connection to a document, a functional textview cursor)
3. some test depend on these resources

While concentrating on these and on "do not throw exceptions here" ... using a [Result type](https://en.wikipedia.org/wiki/Result\_type) as a return value from precondition checking code seemed a good fit:
While concentrating on these and on "do not throw exceptions here" ... using a [Result type](https://en.wikipedia.org/wiki/Result_type) as a return value from precondition checking code seemed a good fit:

* Instead of throwing an exception, we can return some data describing the problem.
* Conceptually it is a data structure that either holds the result (of a computation) or and error value.
Expand Down
20 changes: 10 additions & 10 deletions docs/code-howtos/openoffice/order-of-appearance.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,31 +27,31 @@ Examples:

## Technically

In LibreOffice, a document has a main text that supports the [XText](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XText.html) interface.\
This allows several types of [XTextContent](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XTextContent.html) to be inserted.
In LibreOffice, a document has a main text that supports the [XText](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XText.html) interface.\
This allows several types of [XTextContent](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XTextContent.html) to be inserted.

* Some of these allow text inside with further insertions.

### Anchors

* Many, but not all XTextContent types support getting a "technical" insertion point or text range through [getAnchor](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XTextContent.html#ae82a8b42f6b2578549b68b4483a877d3).
* Many, but not all XTextContent types support getting a "technical" insertion point or text range through [getAnchor](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XTextContent.html#ae82a8b42f6b2578549b68b4483a877d3).
* In Libreoffice positioning both a frame and its anchor seems hard: moving the frame tends to also move the anchor.
* Consequence: producing an order of appearance for the citation groups based solely on `getAnchor` calls may be impossible.
* Allowing or requiring the user to insert "logical anchors" for frames and other "floating" parts might help to alleviate these problems.

### Sorting within a `Text`

The text ranges occupied by the citation markers support the [XTextRange](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XTextRange.html) interface.
The text ranges occupied by the citation markers support the [XTextRange](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XTextRange.html) interface.

* These provide access to the XText they are contained in.
* The [Text](https://api.libreoffice.org/docs/idl/ref/servicecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1Text.html) service may support (optional) the [XTextRangeCompare](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XTextRangeCompare.html) interface, that allows two XTextRange values to be compared if both belong to this `Text`
* The [Text](https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1text_1_1Text.html) service may support (optional) the [XTextRangeCompare](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XTextRangeCompare.html) interface, that allows two XTextRange values to be compared if both belong to this `Text`

### Visual ordering

* The cursor used by the user is available as an [XTextViewCursor](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XTextViewCursor.html)
* If we can get it and can set its position in the document to each XTextRange to be sorted, and ask its [getPosition](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1text\_1\_1XTextViewCursor.html#a9b2bafd342ef75b5d504a9313dbb1389) to provide coordinates "relative to the top left position of the first page of the document.", then we can sort by these coordinates in top-to-bottom left-to-right order.
* The cursor used by the user is available as an [XTextViewCursor](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XTextViewCursor.html)
* If we can get it and can set its position in the document to each XTextRange to be sorted, and ask its [getPosition](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1text_1_1XTextViewCursor.html#a9b2bafd342ef75b5d504a9313dbb1389) to provide coordinates "relative to the top left position of the first page of the document.", then we can sort by these coordinates in top-to-bottom left-to-right order.
* Note: in some cases, for example when the cursor is in a comment (as in `Libreoffice:[menu:Insert]/[Comment]`), the XTextViewCursor is not available (I know of no way to get it).
* In some other cases, for example when an image is selected, the XTextViewCursor we normally receive is not 'functional': we cannot position it for getting coordinates for the citation marks. The [FunctionalTextViewCursor](https://github.com/antalk2/jabref/blob/improve-reversibility-rebased-03/src/main/java/org/jabref/model/openoffice/rangesort/FunctionalTextViewCursor.java) class can solve this case by accessing and manipulating the cursor through [XSelectionSupplier](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1view\_1\_1XSelectionSupplier.html)
* In some other cases, for example when an image is selected, the XTextViewCursor we normally receive is not 'functional': we cannot position it for getting coordinates for the citation marks. The [FunctionalTextViewCursor](https://github.com/antalk2/jabref/blob/improve-reversibility-rebased-03/src/main/java/org/jabref/model/openoffice/rangesort/FunctionalTextViewCursor.java) class can solve this case by accessing and manipulating the cursor through [XSelectionSupplier](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1view_1_1XSelectionSupplier.html)

Consequences of getting these visual coordinates and using them to order the citation markers

Expand All @@ -63,11 +63,11 @@ Consequences of getting these visual coordinates and using them to order the cit

## JabRef

Jabref uses the following steps for sorting sorting citation markers (providing `globalOrder`):
Jabref uses the following steps for sorting citation markers (providing `globalOrder`):

1. the textranges of citation marks in footnotes are replaced by the textranges of the footnote marks.
2. get the positions (coordinates) of these marks
3. sort in top-to-botton left-to-right order
3. sort in top-to-bottom left-to-right order

`(problem)` In JabRef5.2 the positions of citation marks within the same footnote become indistinguishable, thus their order after sorting may differ from their order in the footnote text.\
This caused problems for
Expand Down
6 changes: 3 additions & 3 deletions docs/code-howtos/openoffice/problems.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Reference marks have some features that make it easy to mess up citations in a d
* If the space separating to citation marks is deleted, the user cannot reliably type between the marks.\
The text typed usually becomes part of one of the marks. No visual clue as to which one.\
Note: `[click:Merge]` then `[click:Separate]` adds a single space between. The user can position the cursor before or after it. In either case the cursor is on a boundary: it is not clear if it is in or out of a reference mark.\
Special case: a reference mark at the start or end of a paragraph: the cursor is usually considered to be within at the coresponding edge.
Special case: a reference mark at the start or end of a paragraph: the cursor is usually considered to be within at the corresponding edge.
* (good) They can be moved (Ctrl-X,Ctrl-V)
* They cannot be copied. (Ctrl-C, Ctrl-V) copies the text without the reference mark.
* Reference marks are lost if the document is saved as docx.
Expand All @@ -60,11 +60,11 @@ It would be nice if we could have a backend with better properties. We probably
## Undo

* JabRef 5.3 does not collect the effects of GUI actions on the document into larger Undo actions.\
This makes the Undo functionality of LO impractial.
This makes the Undo functionality of LO impractical.
* `(change)` collect the effects of GUI actions into large chunks: now a GUI action can be undone with a single click.
* except the effect on pageInfo: that is stored at the document level and is not restored by Undo.

## Block screen refresh

* LibreOffice has support in [XModel](https://api.libreoffice.org/docs/idl/ref/interfacecom\_1\_1sun\_1\_1star\_1\_1frame\_1\_1XModel.html#a7b7d36374033ee9210ec0ac5c1a90d9f) to "suspend some notifications to the controllers which are used for display updates."
* LibreOffice has support in [XModel](https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1frame_1_1XModel.html#a7b7d36374033ee9210ec0ac5c1a90d9f) to "suspend some notifications to the controllers which are used for display updates."
* `(change)` Now we are using this facility.
2 changes: 1 addition & 1 deletion docs/code-howtos/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Imagine you want to test the method `format(String value)` in the class `BracesF
}
```

we would have five tests containing a single `assert` statement and named accordingly (`formatDoesNotChangeStringWithoutBraces`, `formatDoesNotRemoveSingleBrace`, , etc.). See [JUnit AntiPattern](https://exubero.com/junit/anti-patterns/#Multiple\_Assertions) for background.
we would have five tests containing a single `assert` statement and named accordingly (`formatDoesNotChangeStringWithoutBraces`, `formatDoesNotRemoveSingleBrace`, , etc.). See [JUnit AntiPattern](https://exubero.com/junit/anti-patterns/#Multiple_Assertions) for background.
* Do _not just test happy paths_, but also wrong/weird input.
* It is recommended to write tests _before_ you actually implement the functionality (test driven development).
* _Bug fixing:_ write a test case covering the bug and then fix it, leaving the test as a security that the bug will never reappear.
Expand Down
2 changes: 1 addition & 1 deletion docs/code-howtos/ui-recommendations.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,5 +22,5 @@ More information: [http://ux.stackexchange.com/a/768](http://ux.stackexchange.co
* Only validate input after leaving the field (or after the user stopped typing for some time)
* The user shouldn't be able to submit the form if there are errors
* However, disabling the submit button in case there are errors is also not optimal. Instead, clicking the submit button should highlight the errors.
* Empty required files shouldn't be marked as invalid until the user a) tries to submit the form or b) focused the field, deleted it contents and then left the field (see [Example](https://www.w3schools.com/tags/tryit.asp?filename=tryhtml5\_input\_required)
* Empty required files shouldn't be marked as invalid until the user a) tries to submit the form or b) focused the field, deleted it contents and then left the field (see [Example](https://www.w3schools.com/tags/tryit.asp?filename=tryhtml5_input_required)
* Ideally, the error message should be shown below the text field and not as a tooltip (so that users quickly understand what's the problem). For example as here [in Boostrap](https://mdbootstrap.com/docs/jquery/forms/validation/?#custom-styles)
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ nav_order: 90

For advanced users, [Eclipse](https://eclipse.org) (`2023-03` or newer) is also possible.
For JDK20 you need to install the additional [support for jdk20 as extension](https://marketplace.eclipse.org/content/java-20-support-eclipse-2023-03-427)).
On Ubuntu Linux, you can follow the [documentation from the Ubuntu Community](https://help.ubuntu.com/community/EclipseIDE#Download\_Eclipse) or the [step-by-step guideline from Krizna](https://www.krizna.com/ubuntu/install-eclipse-in-ubuntu-12-04/) to install Eclipse.
On Ubuntu Linux, you can follow the [documentation from the Ubuntu Community](https://help.ubuntu.com/community/EclipseIDE#Download_Eclipse) or the [step-by-step guideline from Krizna](https://www.krizna.com/ubuntu/install-eclipse-in-ubuntu-12-04/) to install Eclipse.
On Windows, download it from [www.eclipse.org](http://www.eclipse.org/downloads/) and run the installer.

For Eclipse, a working Java (Development Kit) 20 installation is required.
Expand Down

0 comments on commit 9e5e5a1

Please sign in to comment.