Update our documentation on updating eSpeak-NG

[SaschaCowley]

Link to issue number:

None

Summary of the issue:

The docs on updating eSpeak-NG were slightly unclear, and had a couple of outdated things in them.

Description of user facing changes

None.

Description of development approach

Updated the eSpeak docs:

• Made it more obvious that as well as updating user_docs/en/changes.md, you also need to update projectDocs/dev/createDevEnvironment.md (this was already included, but it was not particularly obvious to me).
• Removed old references to the eSpeak version being in nvdaHelper/espeak/config.h, as it is now in nvdaHelper/espeak/sconstruct.
• Fixed up markdown formatting problems.

Testing strategy:

Known issues with pull request:

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

Summary by CodeRabbit

• Documentation
  • Improved formatting and organization of the eSpeak speech synthesizer documentation for better clarity.
  • Emphasized the need to update the /DPACKAGE_VERSION in the sconscript.
  • Refined the known issues section to clarify limitations regarding emoji dictionary files.

[coderabbitai]

Walkthrough

The recent updates to the eSpeak documentation enhance clarity and usability for users involved in building and updating eSpeak within the NVDA framework. Changes include improved formatting, clearer instructions regarding file paths, and specific notes about version updates. The documentation now effectively guides users through necessary steps and highlights known issues, ensuring a smoother integration process.

Changes

Files	Change Summary
include/espeak.md	Reformatted documentation for clarity, consolidated references, and emphasized important updates.

Possibly related issues

• Update eSpeak for 2024.4 #16775: The changes in include/espeak.md provide updated instructions relevant to the issue's objective of updating eSpeak for version 2024.4, improving the overall guidance for this update.

---

Recent review details

Configuration used: .coderabbit.yml
Review profile: CHILL

Commits

Files that changed from the base of the PR and between b8de34e and b776091.

Files selected for processing (1)

• include/espeak.md (4 hunks)

Additional context used

Path-based instructions (1)

include/espeak.md (2)

Pattern **/*: Focus on code smells, logic errors, edge cases, missing test cases, security flaws and serious issues. Avoid commenting on minor issues such as linting, formatting and style issues. This project uses tabs instead of spaces, do not suggest usage of spaces over tabs. Are there any 'red flags' in this code that might warrant closer investigation from a security standpoint? Explain what makes them suspicious. When providing code suggestions, particularly when requested, ensure GitHub's suggestion format is used, i.e.: suggestion <code changes>

---

Pattern **/*.md: Focus on grammar, spelling, and punctuation. Also consider readability and clarity of contents. Ensure that changes follow the style of one sentence per line, suggest changes if this is not met.

LanguageTool

include/espeak.md

[uncategorized] ~15-~15: It appears that a hyphen is missing (if ‘auto’ is not used in the context of ‘cars’).
Context: ...ways kept up to date. We don't use the auto make files or the visual studio files, we ma...

(AUTO_HYPHEN)

---

[style] ~75-~75: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...cluded from the build, they are deleted prior to compiling the dictionaries in the [`nvd...

(EN_WORDINESS_PREMIUM_PRIOR_TO)

---

[style] ~83-~83: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...k-ng/blob/master/src/espeak-ng.1.ronn) (note also [speak-ng command line](https://github....

(ALSO_PLACEMENT)

---

[typographical] ~84-~84: Consider adding a comma after ‘historically’ for more clarity.
Context: ...of eSpeak, locally on Windows. However, historically the Windows build for espeak-ng hasn't ...

(RB_LY_COMMA)

Additional comments not posted (5)

include/espeak.md (5)

15-15: Consider hyphenating "auto make files".

To improve clarity, hyphenate "auto make files" as "auto-make files" since it refers to files related to automake.

We don't use the auto-make files or the visual studio files, we maintain our own method of building eSpeak.

Tools

LanguageTool

[uncategorized] ~15-~15: It appears that a hyphen is missing (if ‘auto’ is not used in the context of ‘cars’).
Context: ...ways kept up to date. We don't use the auto make files or the visual studio files, we ma...

(AUTO_HYPHEN)

---

39-42: Ensure consistent bullet point formatting.

To maintain consistency with the rest of the document, change hyphens to asterisks for bullet points.

* The preprocessor definition is used to supply these definitions instead of [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h)
* [`nvdaHelper/espeak/config.h`](../nvdaHelper/espeak/config.h) must exist (despite being empty) since a "config.h" is included within eSpeak.
* Compare to eSpeak source config: [`include/espeak/src/windows/config.h`](./espeak/src/windows/config.h).
* Diff `src/windows/config.h` with the previous commit.

---

75-75: Consider simplifying "prior to".

The phrase "prior to" can be replaced with "before" for a more concise expression.

from the build, they are deleted before compiling the dictionaries in the

Tools

LanguageTool

[style] ~75-~75: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...cluded from the build, they are deleted prior to compiling the dictionaries in the [`nvd...

(EN_WORDINESS_PREMIUM_PRIOR_TO)

---

83-83: Reposition "also" for better flow.

To improve the sentence flow, move "also" before the verb.

(note [also speak-ng command line](https://github.com/espeak-ng/espeak-ng/blob/master/src/speak-ng.1.ronn))

Tools

LanguageTool

[style] ~83-~83: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...k-ng/blob/master/src/espeak-ng.1.ronn) (note also [speak-ng command line](https://github....

(ALSO_PLACEMENT)

---

84-84: Consider adding a comma after "historically".

Adding a comma after "historically" would improve clarity by clearly separating the introductory adverb.

However, historically, the Windows build for espeak-ng hasn't been well maintained, with periods of build failures.

Tools

LanguageTool

[typographical] ~84-~84: Consider adding a comma after ‘historically’ for more clarity.
Context: ...of eSpeak, locally on Windows. However, historically the Windows build for espeak-ng hasn't ...

(RB_LY_COMMA)

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.