From fd8cca4a00d90f3d51b38379107e463d028a9244 Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 17 Oct 2022 00:03:05 +0200 Subject: devdoc: move design notes to proper directory --- devdoc/design-notes.md | 239 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 devdoc/design-notes.md (limited to 'devdoc') diff --git a/devdoc/design-notes.md b/devdoc/design-notes.md new file mode 100644 index 0000000..0d7b5c1 --- /dev/null +++ b/devdoc/design-notes.md @@ -0,0 +1,239 @@ +# ldgallery design notes + +_ldgallery_ consists of two main components that are packaged and distributed together, but are otherwise functionally independent: + +* a __compiler__ which turns a collection of pictures and sidecar metadata files into their compressed/normalised and aggregated versions respectively, and +* a web __viewer__ in the form of a single-page application, rendering the output of the compiler as a searchable picture gallery. + + +## Gallery compiler + +### Input + +#### Directory structure + +The compiler takes a source directory as input which shall contain item resource files and associated metadata sidecar files. Those items may be recursively grouped into multiple levels of sub-directories. + +Example source directory structure: + +``` +example-gallery-source +├── _DSC8808-1.jpg -- a picture +├── _DSC8808-1.jpg.yaml -- its associated sidecar metadata file +└── Glacier 3000 -- a directory grouping gallery items + ├── thumbnail.jpg -- optional directory thumbnail + ├── _DSC5475.jpg + ├── _DSC5475.jpg.yaml + ├── _DSC5542.jpg + └── _DSC5542.jpg.yaml +``` + + +#### Metadata sidecar file + +Metadata associated to items are stored in YAML sidecar files of the same name, with the `.yaml` extension appended. The use of plain text sidecar files allow for easier editing without any special tool in a unified manner for multiple types of files (pictures, videos, ebooks, ...). The metadata contained within item files are simply ignored. + +Tags are given with a group hierarchy separated by `.`, which allows generic searches as well as implicit disambiguation. + +Example metadata sidecar file: + +```yaml +title: Some title + +date: 2019-12-20T16:51:52+00:00 + +description: > + Some multiline description + that may contain some markdown later. + +tags: + - photographer.someone + - location.france.paris + - monochromatic +``` + +Possible evolutions: + +* Fallback values may later be defined for each field, making them optional. +* The description field could be allowed to contain markdown-formatted content, which would be rendered by the __viewer__ app. +* Other keys could be added to allow the definition of specific transform/compilation/displaying parameters on a particular file. +* Metadata sidecar files could be added for directories as well in some `index.yaml` file. + + +#### Gallery configuration file + +The gallery YAML configuration file contains the __compiler__'s and the __viewer__'s settings in two different sections. + +Proposed configuration file, named `gallery.yaml` at the root of the source directory: + +```yaml +compiler: + galleryName: My Little Gallery + ignoreFiles: .*\.txt # to ignore text files + implicitDirectoryTag: false # default + + thumbnailMaxResolution: + width: 400 # default + height: 400 # default + + pictureMaxResolution: # or unspecified to copy files as is + width: 1024 + height: 768 + + # format normalisation? + # item compression? + + +viewer: + # TODO: configuration options to be defined + # separately shown tags and their colours + # use hash in URL (useful for use without webserver url rewrite)? +``` + + +### Output + +#### Directory structure + +``` +data +├── items -- original/normalised item directory +│ ├── _DSC8808-1.jpg +│ └── Glacier 3000 +│ ├── _DSC5475.jpg +│ └── _DSC5542.jpg +├── thumbnails -- item thumbnails directory +│ ├── _DSC8808-1.jpg +│ └── Glacier 3000 +│ ├── thumbnail.jpg +│ ├── _DSC5475.jpg +│ └── _DSC5542.jpg +├── index.json -- content index file +└── viewer.json -- viewer configuration file +``` + + +#### Viewer configuration file + +The content of the `viewer` section of the gallery configuration file is used, without any transformation by the __compiler__, to generate the `viewer.json` file located at the root of the output directory. + + +#### Gallery items index + +The __compiler__ generates a global index file `index.json` aggregating the metadata of all the source sidecar files as a tree of items as described below. Its root node is a directory item. The type of each property node is marked by its `type` field. + +Directory items aggregate their tags from the items below it in order to be displayed in search results. + +Resource paths are rooted with respect to the data output directory which serves as the base path. + +Serialised item structure: + +```json +{ + "_comment": "common fields", + + "title": "Some title", + "date": "2019-12-20T16:51:52+00:00", + "description": "Some multiline description\nthat may contain some markdown later.", + + "tags": [ + "photographer.someone", + "location.france.paris", + "monochromatic" + ], + + "path": "[resource path]", + + "thumbnail": null | { + "resource": "[resource path]", + "resolution": { + "width": 400, + "height": 200 + } + }, + + + "_comment": "type-dependent", + + "properties": { + "type": "picture", + "resource": "[resource url]" + }, + + "properties": { + "type": "other", + "resource": "[resource url]" + }, + + "properties": { + "type": "directory", + "items": [ { "_comment": "item objects..." } ] + } +} +``` + + +#### Normalised items and thumbnails + +Gallery items are normalised and made available in the `items` sub-directory of the data output directory. Normalisation consists of optional transcoding and other transforms as configured by the user in the compiler part of the `gallery.yaml` configuration file. + +Thumbnails are also generated for those items and are placed in the `thumbnails` sub-directory. Thumbnails of pictures in particular are resized using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails may later be generated by picking or assembling one or multiple of its items, or defined explicitely by the user. + +The structure of the input directory is kept in both those output sub-directories. Input item files and directories also keep their original names. + + +## Gallery viewer + +The __viewer__ is a single-page web application which displays the gallery's content. + +It runs fully on the client's side and remains usable without any back-end. It renders the compiled resources from the `data` directory, placed at its root, generated by the __compiler__. + + +### URL anchor + +The page anchor is updated and used by the application to reflect the state of its current state in such a way that any view can be shared and loaded back by copying the URL and its anchor. It should in particular contain the current directory or item, as well as the filtering query. + + +### Directory/collection/grid view + +The application starts by showing a grid view of the root directory of the gallery. + +This combined view offers the possiblity to the user to navigate to other items and to search recursively through the current directory. + + +#### Directory breadcrumbs + +The directory view displays the current directory path, with links allowing the user to navigate into parent ones. + +``` +Gallery / Some directory / Sub-directory +``` + + +#### Filering query + +A query field allows the user to search through and filter the items of the current directory and its sibling items recursively. This search field allows restriction on tags in a hierarchical manner. It should feature some sort of autocompletion, as well as an adjacent list of tags that are available for filtering. Positive as well as negative filtering should be possible, allowing the user to exclude some tags from the search results. + +For instance, the query `france -chessy` should match an item tagged with `location.france.paris`, but not `location.france.chessy`. + +The search is performed on the client side, either by scanning the item tree or with the use on some client-side indexer such as [Elasticlunr]. + +In addition to tag-based filtering, full-text search on the `title` and `description` could later be added by leveraging such indexer. + +[Elasticlunr]: http://elasticlunr.com/ + + +#### Thumbnail grid + +The content of a directory are displayed as a grid of thumbnails which allows to navigate through sub-directories and to view items. + +By default, the content is rendered in the same ordered as listed in `index.json`. The user could later be presented with a menu allowing to sort those items by name, date for example. + + +### Item view + +Items other than directories are displayed by this view, making use of most of the screen space to render the element. + +This view should as well display the title, description, date, tags and other information associated to the item. Tags in particular are displayed in a grouped manner as determined in `index.json`. + +It should be possible to navigate between items of the same directory as the current one through a thumbnail reel and previous/next links. -- cgit v1.2.3 From 9c73ce37e76925b70fbef27bc8d14dab4fa59aca Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 17 Oct 2022 00:05:10 +0200 Subject: devdoc/design-notes: wrap long lines for easier diffing --- devdoc/design-notes.md | 122 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 89 insertions(+), 33 deletions(-) (limited to 'devdoc') diff --git a/devdoc/design-notes.md b/devdoc/design-notes.md index 0d7b5c1..9bca7c8 100644 --- a/devdoc/design-notes.md +++ b/devdoc/design-notes.md @@ -1,9 +1,13 @@ # ldgallery design notes -_ldgallery_ consists of two main components that are packaged and distributed together, but are otherwise functionally independent: +_ldgallery_ consists of two main components that are packaged and distributed +together, but are otherwise functionally independent: -* a __compiler__ which turns a collection of pictures and sidecar metadata files into their compressed/normalised and aggregated versions respectively, and -* a web __viewer__ in the form of a single-page application, rendering the output of the compiler as a searchable picture gallery. +* a __compiler__ which turns a collection of pictures and sidecar metadata + files into their compressed/normalised and aggregated versions respectively, + and +* a web __viewer__ in the form of a single-page application, rendering the + output of the compiler as a searchable picture gallery. ## Gallery compiler @@ -12,7 +16,9 @@ _ldgallery_ consists of two main components that are packaged and distributed to #### Directory structure -The compiler takes a source directory as input which shall contain item resource files and associated metadata sidecar files. Those items may be recursively grouped into multiple levels of sub-directories. +The compiler takes a source directory as input which shall contain item +resource files and associated metadata sidecar files. Those items may be +recursively grouped into multiple levels of sub-directories. Example source directory structure: @@ -31,9 +37,14 @@ example-gallery-source #### Metadata sidecar file -Metadata associated to items are stored in YAML sidecar files of the same name, with the `.yaml` extension appended. The use of plain text sidecar files allow for easier editing without any special tool in a unified manner for multiple types of files (pictures, videos, ebooks, ...). The metadata contained within item files are simply ignored. +Metadata associated to items are stored in YAML sidecar files of the same name, +with the `.yaml` extension appended. The use of plain text sidecar files allow +for easier editing without any special tool in a unified manner for multiple +types of files (pictures, videos, ebooks, ...). The metadata contained within +item files are simply ignored. -Tags are given with a group hierarchy separated by `.`, which allows generic searches as well as implicit disambiguation. +Tags are given with a group hierarchy separated by `.`, which allows generic +searches as well as implicit disambiguation. Example metadata sidecar file: @@ -55,16 +66,21 @@ tags: Possible evolutions: * Fallback values may later be defined for each field, making them optional. -* The description field could be allowed to contain markdown-formatted content, which would be rendered by the __viewer__ app. -* Other keys could be added to allow the definition of specific transform/compilation/displaying parameters on a particular file. -* Metadata sidecar files could be added for directories as well in some `index.yaml` file. +* The description field could be allowed to contain markdown-formatted content, + which would be rendered by the __viewer__ app. +* Other keys could be added to allow the definition of specific + transform/compilation/displaying parameters on a particular file. +* Metadata sidecar files could be added for directories as well in some + `index.yaml` file. #### Gallery configuration file -The gallery YAML configuration file contains the __compiler__'s and the __viewer__'s settings in two different sections. +The gallery YAML configuration file contains the __compiler__'s and the +__viewer__'s settings in two different sections. -Proposed configuration file, named `gallery.yaml` at the root of the source directory: +Proposed configuration file, named `gallery.yaml` at the root of the source +directory: ```yaml compiler: @@ -115,16 +131,23 @@ data #### Viewer configuration file -The content of the `viewer` section of the gallery configuration file is used, without any transformation by the __compiler__, to generate the `viewer.json` file located at the root of the output directory. +The content of the `viewer` section of the gallery configuration file is used, +without any transformation by the __compiler__, to generate the `viewer.json` +file located at the root of the output directory. #### Gallery items index -The __compiler__ generates a global index file `index.json` aggregating the metadata of all the source sidecar files as a tree of items as described below. Its root node is a directory item. The type of each property node is marked by its `type` field. +The __compiler__ generates a global index file `index.json` aggregating the +metadata of all the source sidecar files as a tree of items as described below. +Its root node is a directory item. The type of each property node is marked by +its `type` field. -Directory items aggregate their tags from the items below it in order to be displayed in search results. +Directory items aggregate their tags from the items below it in order to be +displayed in search results. -Resource paths are rooted with respect to the data output directory which serves as the base path. +Resource paths are rooted with respect to the data output directory which +serves as the base path. Serialised item structure: @@ -175,35 +198,53 @@ Serialised item structure: #### Normalised items and thumbnails -Gallery items are normalised and made available in the `items` sub-directory of the data output directory. Normalisation consists of optional transcoding and other transforms as configured by the user in the compiler part of the `gallery.yaml` configuration file. +Gallery items are normalised and made available in the `items` sub-directory of +the data output directory. Normalisation consists of optional transcoding and +other transforms as configured by the user in the compiler part of the +`gallery.yaml` configuration file. -Thumbnails are also generated for those items and are placed in the `thumbnails` sub-directory. Thumbnails of pictures in particular are resized using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails may later be generated by picking or assembling one or multiple of its items, or defined explicitely by the user. +Thumbnails are also generated for those items and are placed in the +`thumbnails` sub-directory. Thumbnails of pictures in particular are resized +using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails +may later be generated by picking or assembling one or multiple of its items, +or defined explicitely by the user. -The structure of the input directory is kept in both those output sub-directories. Input item files and directories also keep their original names. +The structure of the input directory is kept in both those output +sub-directories. Input item files and directories also keep their original +names. ## Gallery viewer -The __viewer__ is a single-page web application which displays the gallery's content. +The __viewer__ is a single-page web application which displays the gallery's +content. -It runs fully on the client's side and remains usable without any back-end. It renders the compiled resources from the `data` directory, placed at its root, generated by the __compiler__. +It runs fully on the client's side and remains usable without any back-end. It +renders the compiled resources from the `data` directory, placed at its root, +generated by the __compiler__. ### URL anchor -The page anchor is updated and used by the application to reflect the state of its current state in such a way that any view can be shared and loaded back by copying the URL and its anchor. It should in particular contain the current directory or item, as well as the filtering query. +The page anchor is updated and used by the application to reflect the state of +its current state in such a way that any view can be shared and loaded back by +copying the URL and its anchor. It should in particular contain the current +directory or item, as well as the filtering query. ### Directory/collection/grid view -The application starts by showing a grid view of the root directory of the gallery. +The application starts by showing a grid view of the root directory of the +gallery. -This combined view offers the possiblity to the user to navigate to other items and to search recursively through the current directory. +This combined view offers the possiblity to the user to navigate to other items +and to search recursively through the current directory. #### Directory breadcrumbs -The directory view displays the current directory path, with links allowing the user to navigate into parent ones. +The directory view displays the current directory path, with links allowing the +user to navigate into parent ones. ``` Gallery / Some directory / Sub-directory @@ -212,28 +253,43 @@ Gallery / Some directory / Sub-directory #### Filering query -A query field allows the user to search through and filter the items of the current directory and its sibling items recursively. This search field allows restriction on tags in a hierarchical manner. It should feature some sort of autocompletion, as well as an adjacent list of tags that are available for filtering. Positive as well as negative filtering should be possible, allowing the user to exclude some tags from the search results. +A query field allows the user to search through and filter the items of the +current directory and its sibling items recursively. This search field allows +restriction on tags in a hierarchical manner. It should feature some sort of +autocompletion, as well as an adjacent list of tags that are available for +filtering. Positive as well as negative filtering should be possible, allowing +the user to exclude some tags from the search results. -For instance, the query `france -chessy` should match an item tagged with `location.france.paris`, but not `location.france.chessy`. +For instance, the query `france -chessy` should match an item tagged with +`location.france.paris`, but not `location.france.chessy`. -The search is performed on the client side, either by scanning the item tree or with the use on some client-side indexer such as [Elasticlunr]. +The search is performed on the client side, either by scanning the item tree or +with the use on some client-side indexer such as [Elasticlunr]. -In addition to tag-based filtering, full-text search on the `title` and `description` could later be added by leveraging such indexer. +In addition to tag-based filtering, full-text search on the `title` and +`description` could later be added by leveraging such indexer. [Elasticlunr]: http://elasticlunr.com/ #### Thumbnail grid -The content of a directory are displayed as a grid of thumbnails which allows to navigate through sub-directories and to view items. +The content of a directory are displayed as a grid of thumbnails which allows +to navigate through sub-directories and to view items. -By default, the content is rendered in the same ordered as listed in `index.json`. The user could later be presented with a menu allowing to sort those items by name, date for example. +By default, the content is rendered in the same ordered as listed in +`index.json`. The user could later be presented with a menu allowing to sort +those items by name, date for example. ### Item view -Items other than directories are displayed by this view, making use of most of the screen space to render the element. +Items other than directories are displayed by this view, making use of most of +the screen space to render the element. -This view should as well display the title, description, date, tags and other information associated to the item. Tags in particular are displayed in a grouped manner as determined in `index.json`. +This view should as well display the title, description, date, tags and other +information associated to the item. Tags in particular are displayed in +a grouped manner as determined in `index.json`. -It should be possible to navigate between items of the same directory as the current one through a thumbnail reel and previous/next links. +It should be possible to navigate between items of the same directory as the +current one through a thumbnail reel and previous/next links. -- cgit v1.2.3 From e04500474a0f35d820c1bcdc7103d770245beb02 Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 17 Oct 2022 00:06:37 +0200 Subject: devdoc/design-notes: add header and outdated warning --- devdoc/design-notes.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'devdoc') diff --git a/devdoc/design-notes.md b/devdoc/design-notes.md index 9bca7c8..b6ea37a 100644 --- a/devdoc/design-notes.md +++ b/devdoc/design-notes.md @@ -1,3 +1,13 @@ +--- +title: ldgallery design notes +author: pacien +date: 2020-02-25 +--- + +__Warning: this document is severely outdated.__ + +--- + # ldgallery design notes _ldgallery_ consists of two main components that are packaged and distributed -- cgit v1.2.3 From 8c8920502d43db5d7540eb0373447be224b219dc Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 24 Oct 2022 19:39:41 +0200 Subject: devdoc: describe the viewer's index as of v2.1 The viewer's internal tag indexing wasn't documented. This is a brief "reverse-engineering" of it accompanied with a few notes about its current issues. This constitutes some preliminary work before writing proper specification to clarify the otherwise undefined, dubious or conflicting behaviours. --- devdoc/viewer_index_v2.1.md | 156 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 devdoc/viewer_index_v2.1.md (limited to 'devdoc') diff --git a/devdoc/viewer_index_v2.1.md b/devdoc/viewer_index_v2.1.md new file mode 100644 index 0000000..c37e925 --- /dev/null +++ b/devdoc/viewer_index_v2.1.md @@ -0,0 +1,156 @@ +--- +title: "Viewer: index v2.1" +author: pacien +date: 2022-10-22 (v2) +--- + +# Abstract + +This is a short documentation of the viewer's internal index dating from the +first version of this software and still currently in use in version 2.1. + +This index was written without proper specifications or documentation, and has +evolved a lot since then. + +This document is an attempt at describing how this index is currently being +generated and used, before further work can be done on some proper +specification to clarify the problematic behaviours. + + +# Document version history + +1. 2022-10-15: call notes +2. 2022-10-22: rewritten + + +# Description of the current implementation + +## Generating the index(es) from the item tree + +The gallery item index (`index.json`) is loaded by the `galleryStore` and made +available as the `galleryIndex` attribute. + +Two indexes are derived from that file through the `indexFactory` service: + +- `tagsIndex`: + - Maps each tag "part" (component) to items tagged with it. + - Maps the left-most disambiguating component to all components on its right. + - Includes a normalised version of the tag for searching. + - (Stores the left-most `rootPart` component. This is not used anywhere). + +- `tagsCategories`: + - Same as `tagsIndex`, but partitioned by tag category prefixes as defined in + the viewer configuration. + + +## Search query input auto-completion "suggestions" + +The `TagInput` component suggests tags as the user types in that input field. + +This is provided by the `indexFactory.searchTags` function in fuzzy +(non-strict) mode, which only uses the global tag index. + +The fuzzy search is implemented as a normalised (lowercase) infix word lookup, +including the disambiguating tag parts. + +The auto-completion suggestions are independent of the current directory. +Suggestions yielding no result (incompatible with the current search query) are +not excluded either. + + +## Item search + +The search query is stored in the URL query. This allows a search to be shared +by copying the current URL. + +This URL search query is updated by `LayoutLeft.vue` to match modifications +made through the tag input or related filters "propositions". This component +also updates the store to match the URL query through `galleryStore.search`. + +A search query consists of three sets of tags: an intersection list, a forced +inclusion (union) list, and a forced exclusion list. The last two are denoted +with a `+` and `-` modifier prefix before the tag name. The order of the terms +does not matter. + +The result computed in `indexSearch.indexSearch` is given by +`(⋂(intersection) ∪ ⋃(forced inclusion)) ∖ ⋃(forced exclusion)`. + +The string representation of a query is parsed in `indexFactory`. It is +serialised by taking the `filter.display` property of filters, in +`LayouLeft.vue` for being displayed in the tag input and in the URL. + + +## Related filters "propositions" + +The left pane of the user interface lists related filters "propositions", +related to the current search results or directory being viewed. + +Tags in that pane are grouped according to the `tagCategories` gallery +configuration key. (This is currently buggy: some tags can appear in the wrong +category under some circumstances). + +The related tags are filtered with respect to the current search query or +directory: only tags that are present on the listed items are shown. + +Each "proposed" tag has an occurrence count of the items having that tag in the +whole gallery. (This is inconsistent with the locality of the filter). + +This is computed using a full gallery search through the `galleryStore` using +`indexFactory.searchTags` in strict (non-fuzzy) mode. + + +# Identified issues and proposals + +## Issues affecting the end users + +- Tags categories and disambiguation aren't properly defined: + - It is not clear whether intermediate tag components should be treated as + tags and suggested at all. (They currently are). + +- Tags with more than two components do not seem to be handled correctly: + - `a:b:c`: `c` is not registered as a child of `a` in `tagsIndex`. + - This seems to be the cause of tags being displayed in the wrong category in + the suggestion pane. + +- The tag input's auto-completion suggests impossible intersections: + - The fuzzy (non-strict) search does not work the same way as the suggestions + panel, which restricts the suggestions. + - This might however be problematic for forced inclusions (union) tags + which are still meaningful. + +- The tag occurrence counts in the related tags "propositions" pane is + misleading: + - This view suggests only the tags for the current search results + (descendants of the current directory and matching the current search query + if any), + - But the occurrence count for each tag is global (on the whole gallery + instead of the current search results). + + +## Issues affecting only the developers + +- Ambiguous terminology: + - For example "index" vs "index.json", or "tag suggestions" vs + "tag propositions" vs "tag completion". + - This confusion is reflected in the component naming and coupling… + - A glossary and would help. + - Refactoring and renaming the modules would help. + +- Tight coupling of the tag-related and index operations: + - It goes all over the place. + - Some concerns should and can clearly be separated for example: + - For example query parsing, compiling and actual run on the item tree. + - The new modules should make use of composition with the rest of the + components. + +- Lack of unit tests: + - Coupling is preventing easy unit testing. + - Once the concerns are separated: + - We'll have clear expected outputs with respect to some input. + - It should be easier to do unit testing: + - (perhaps through randomised property testing). + +- Minor: relatively verbose and intertwined imperative code: + - The query parsing and recursive tree operations would probably be more + elegant in PureScript than Javascript/Typescript. + - Same with unit and property tests. -- cgit v1.2.3 From 4ac5193b38cb59e72abde4deac67d81a9e0e356f Mon Sep 17 00:00:00 2001 From: pacien Date: Tue, 25 Oct 2022 18:25:26 +0200 Subject: devdoc/index-v2.1: include review remarks --- devdoc/viewer_index_v2.1.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'devdoc') diff --git a/devdoc/viewer_index_v2.1.md b/devdoc/viewer_index_v2.1.md index c37e925..0595a55 100644 --- a/devdoc/viewer_index_v2.1.md +++ b/devdoc/viewer_index_v2.1.md @@ -1,7 +1,7 @@ --- title: "Viewer: index v2.1" author: pacien -date: 2022-10-22 (v2) +date: 2022-10-25 (v3) --- # Abstract @@ -19,8 +19,9 @@ specification to clarify the problematic behaviours. # Document version history -1. 2022-10-15: call notes -2. 2022-10-22: rewritten +1. 2022-10-15 by pacien: call notes +2. 2022-10-22 by pacien: rewritten +3. 2022-10-25 by pacien: include feedbacks from zeroinformatique # Description of the current implementation @@ -34,8 +35,9 @@ Two indexes are derived from that file through the `indexFactory` service: - `tagsIndex`: - Maps each tag "part" (component) to items tagged with it. - - Maps the left-most disambiguating component to all components on its right. + - Maps tags to their immediately preceding disambiguating component as child. - Includes a normalised version of the tag for searching. + - Stores the `childPart`, used to generate tag categories indexes. - (Stores the left-most `rootPart` component. This is not used anywhere). - `tagsCategories`: @@ -55,7 +57,9 @@ including the disambiguating tag parts. The auto-completion suggestions are independent of the current directory. Suggestions yielding no result (incompatible with the current search query) are -not excluded either. +not excluded either. The current implementation makes the choice of suggesting +everything because the current index does not allow finer filtering, and +because walking the whole item tree may lead to performance issues. ## Item search @@ -107,8 +111,14 @@ This is computed using a full gallery search through the `galleryStore` using - It is not clear whether intermediate tag components should be treated as tags and suggested at all. (They currently are). -- Tags with more than two components do not seem to be handled correctly: - - `a:b:c`: `c` is not registered as a child of `a` in `tagsIndex`. +- Tags with indirect disambiguations are not handled correctly: + - Example in `a:b:c`: + - `b` is a child of `a`, `c` is a child of `b`. + - But `c` is not registered as a child of `a` in `tagsIndex`. + +- Homonymous disambiguated tags are not handled in separate categories. + - Example with `a` and `b:a`: + - `a` seems to be shown under category `b`. - This seems to be the cause of tags being displayed in the wrong category in the suggestion pane. @@ -117,6 +127,7 @@ This is computed using a full gallery search through the `galleryStore` using panel, which restricts the suggestions. - This might however be problematic for forced inclusions (union) tags which are still meaningful. + - They could still be listed but greyed for example. - The tag occurrence counts in the related tags "propositions" pane is misleading: -- cgit v1.2.3