PARQUET-2480: Clarify what "page index" means in Parquet.thrift

[alamb]

https://issues.apache.org/jira/browse/PARQUET-2480

See the proposed update as rendered markdown: https://github.com/alamb/parquet-format/blob/alamb/page-index/PageIndex.md

I have always found it very confusing that people refer to the term parquet "page index", for example this message

However, the term "page index" is not used in the the parquet.thrift file itself, but only appears as the name of the file that describes the ColumnIndex and OffsetIndex, PageIndex.md

This means I can't search for "page index" in the spec and find out what people are talking about

Proposed Clarifications

1. Update the introductory paragraph of PageIndex.md to clarify use the term "page index" and explain that it is encoded as ColumnIndex and OffsetIndex
2. Update the description of ColumnIndex and OffsetIndex to include the term "page index" and clarify what those structures are used for.

Jira

• [x] My PR addresses the following Parquet Jira issues and references them in the PR title. For example, "PARQUET-1234: My Parquet PR"
  • https://issues.apache.org/jira/browse/PARQUET-2480
  • In case you are adding a dependency, check if the license complies with the ASF 3rd Party License Policy.

Commits

• [x] My commits all reference Jira issues in their subject lines. In addition, my commits follow the guidelines from "How to write a good git commit message":
  1. Subject is separated from body by a blank line
  2. Subject is limited to 50 characters (not including Jira issue reference)
  3. Subject does not end with a period
  4. Subject uses the imperative mood ("add", not "adding")
  5. Body wraps at 72 characters
  6. Body explains "what" and "why", not "how"

Documentation

This PR has no spec changes, only clarifications

• [x] In case of new functionality, my PR adds documentation that describes how to use it.
  • All the public functions and the classes in the PR contain Javadoc that explain what it does

[mapleFU]

I also think that currently PageIndex means "offset index and column index". They're all page-level index

[alamb]

Thank you for the comments @mapleFU @tustvold and @wgtmac - I believe I have implemented your suggestions and I think the PR is much clearer because of it.

[wgtmac]

@gszadovszky @pitrou @emkornfield @julienledem Would you like to take a look?