[jira] [Created] (TIKA-4746) tika-4.0.0-alpha1 - General Documentation Comments

["Adrian Bird (Jira)" <ji...@apache.org>]

Adrian Bird created TIKA-4746:
---------------------------------

             Summary: tika-4.0.0-alpha1 - General Documentation Comments
                 Key: TIKA-4746
                 URL: https://issues.apache.org/jira/browse/TIKA-4746
             Project: Tika
          Issue Type: Bug
    Affects Versions: 4.0.0
            Reporter: Adrian Bird


Here are some comments/thoughts etc. from looking at the updated, and unchanged, documentation. Some comments may not be valid if associated code changes have also been made (which I haven't checked). 
I've only really looked at the Tika App / Pipes / File System combination, although I have skimmed most of the others.

On the web documentation pages there is a static 'Contents' table in the top right that doesn't move when you scroll down. It is missing on the following pages:
- using-tika/index.adoc
- configuration/index.adoc
- maintainers/index.adoc
Also, these pages don't open when you click the closed triangle image.

General point - sometimes you use 'Solr' and 'Kafka' and sometimes 'Apache Solr' and 'Apache Kafka'. Should they all be one or the other?

using-tika/cli/index.adoc
- Command Line Options - this lists a subset of the options. Shouldn't it list all of them i.e. cover the same list that is output when doing `--help`.
- Tika Pipes processing (the first one) - I think this could be removed as it is covered in detail later.
- Extract Markdown from a file - I think `Extract Markdown from a file` would fit better after `Extract metadata as JSON`.
- How Pipes mode is activated (2nd bullet) - with the released code I get an exception if I specify both `--input` and `--output`.
- How Pipes mode is activated (2nd bullet) - some of the options are not in the Batch Options list below.
- Tika Pipes Options - I would expect this list to match what is output when doing `--help`.
- Tika Pipes Examples - the formatting is different for these examples and the ones above

pipes/index.adoc
- question - why is there a section on Emitters in this page, rather than in the Emitters page?

pipes/getting-started.adoc
- JSON Configuration - 1st Note - EMIT_INTERMEDIATE_RESULTS is also a placeholder token
- JSON Configuration example - there should be a '=' in '--config tika-config.json'

pipes/iterators.adoc
- why does it say 'they are not wrapped in a baseConfig block.' This is the only mention of 'baseConfig' in the documentation.

pipes/configuration.adoc
- Filesystem-to-filesystem pipeline - EMIT_INTERMEDIATE_RESULTS is also a placeholder token

pipes/parse-modes.adoc
- Content Handler Types - this mentions 'ContentHandlerFactory' and 'parseContext' which seem like Java names and not JSON Config names.
- CLI Usage - should it be "The tika-app pipes processor ..." rather than 'batch'

pipes/unpack-config.adoc
- Quick Start - 'ParseMode.UNPACK' doesn't reflect what is in the config.
- Configuration Options - this should say that these options are defined within the 'unpack-config' key.
- Enabling Frictionless Output -is 'UnpackConfig' ok here or should it be 'unpack-config'.
- CLI Usage - I don't see the '--unpack' option in the `--help` output
 
pipes/timeouts.adoc
- CLI Usage - the output from '--help' doesn't seem to show that '--fork' etc. can be used in Pipes mode.

pipes/troubleshooting.adoc
- Log levels and sensitive data - I didn't see any documentation about logging in general and setting log levels.

pipes/plugins/filesystem.adoc
- Complete Pipeline Example - EMIT_INTERMEDIATE_RESULTS is also a placeholder token
- File System Reporter (file-system-reporter)- Configuration - statusFile - Does this have to be an absolute path and not a relative path? If so it would be worth saying..
- Status file schema - counts - in my file I'm seeing 'statusCounts' and not 'counts'
- Status file schema - timestamp - in my file I'm seeing 'lastUpdate' rather than 'timestamp'
- Status file schema - in my file I'm also seeing 'started'

configuration/index.adoc
- I don't see a general overview of the configuration structure here (I know Pipes configuration is covered elsewhere). If a user new to Tika comes here and is starting with V4 they need more of an overview than is currently here e.g. it should cover the top level keys in a JSON config file.
- There are no links to the VML Parsers, External Parser and Tess4J OCR pages.

configuration/digesters.adoc
- Supported Algorithms - the output from '--help' does not mention the last three - should it?
 
migration-to-4x/serialization-4x.adoc
- Friendly Naming Convention - not really specific to this page, but how do users know what the friendly names are. Running the 'list--*' options all produce class names. 

advanced/index.adoc 
- it looks like all the topic entries are geared towards using the Java API and aren't available through the CLI and JSON configuration, with the exception of 'Setting Limits'. Is it worth adding text to this effect?
 
advanced/language-detection.adoc 
- Overriding Model Selection - says 'Or via Tika’s JSON configuration mechanism if you are using SelfConfiguring component loading' - how can it be specified in a JSON config file.

 



--
This message was sent by Atlassian Jira
(v8.20.10#820010)