Skip to content

Fix up bad syntax for documentation#15939

Merged
seanbudd merged 6 commits intobetafrom
fixupSyntax
Dec 21, 2023
Merged

Fix up bad syntax for documentation#15939
seanbudd merged 6 commits intobetafrom
fixupSyntax

Conversation

@seanbudd
Copy link
Copy Markdown
Member

@seanbudd seanbudd commented Dec 19, 2023

Link to issue number:

Partially #13333

Summary of the issue:

To aid with converting to markdown, fixing txt2tags syntax issues will ensure the conversion works as expected.
Note that not all syntax issues are fixed, however this PR intends to catch easy fixes that can be fixed with regex.
This may result in bad syntax in the markdown files, however these are syntax issues in the current documentation so conversion is unlikely to be a step in a worse direction.

Description of user facing changes

None

Description of development approach

Regex groups:

  • ([^`])`([^`]) replaced with $1``$2
  • ^ ( )*- to detect lists indented by an odd number of spaces

Unmaintained files in user_docs have been removed

Testing strategy:

Sanity check built docs

Known issues with pull request:

None

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.

@seanbudd seanbudd requested review from a team as code owners December 19, 2023 03:02
@seanbudd seanbudd added this to the 2024.1 milestone Dec 19, 2023
@AppVeyorBot
Copy link
Copy Markdown

See test results for failed build of commit ceeaffd563

@AppVeyorBot
Copy link
Copy Markdown

See test results for failed build of commit fdb1a8b37b

@seanbudd seanbudd changed the base branch from master to beta December 19, 2023 04:33
@seanbudd seanbudd closed this Dec 19, 2023
@seanbudd seanbudd reopened this Dec 19, 2023
@AppVeyorBot
Copy link
Copy Markdown

See test results for failed build of commit b1f8ec036f

- [Microsoft Speech Platform - Runtime (Version 11), x86 https://www.microsoft.com/download/en/details.aspx?id=27225]
- [Microsoft Speech Platform - Runtime Languages (Version 11) https://www.microsoft.com/download/en/details.aspx?id=27224]
- This page includes many files for both speech recognition and text-to-speech.
- This page includes many files for both speech recognition and text-to-speech.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sublist not needed here.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd like to keep this one. I think there is some value for readability with keeping the component link visually separate to the extra information

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, no problem. It was just an suggestion (optional).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to @tiago-casal in #13333 (comment) dated Feb 13, 2022 and following comments:

The pt_BR/developerGuide.t2t translation is being updated, but it will take a while to get ready.

@tiago-casal any update on this and any opinion with this removal?

As an alternative to manual translation of the dev guide, see #15853.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to @tiago-casal in #13333 (comment) dated Feb 13, 2022 and following comments:

The pt_BR/developerGuide.t2t translation is being updated, but it will take a while to get ready.

@tiago-casal any update on this and any opinion with this removal?

As an alternative to manual translation of the dev guide, see #15853.

Hello!

Unfortunately it has not yet been completed; work remains in progress.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Adriani90, any opinion on this removal. Feel free to tag other German translators if needed.

As an alternative to manual translation of the dev guide, see #15853.

@Adriani90
Copy link
Copy Markdown
Collaborator

Actually I didn't really know the developer guide can be translated, but I think it is good to have it for german and also other languages. I think we can promote its translation into the local communities. It's just a matter of communication. Maybe I can take this into the community, so please don't remove it.
Why is the commands txt file in the Thai language removed? Are we sure it is not maintained? Or maybe the people there do not know how to translate it?

I wouldn't remove these things without consulting the community first. i.e. for the zh folder the community actually requested it in #9524.

Note that such things might get attention 10 years later or what ever, if suddenly someone is motivated to do it. So I think we should not restrict the potential for this by removing things that are not requested by the community.

Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>
Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>
@AppVeyorBot
Copy link
Copy Markdown

See test results for failed build of commit 72dfc95ff1

@seanbudd
Copy link
Copy Markdown
Member Author

I will be restoring the developerGuides to reconsider whether or not we will include these in crowdin

@CyrilleB79
Copy link
Copy Markdown
Contributor

I will be restoring the developerGuides to reconsider whether or not we will include these in crowdin

It is worth noting that both translated dev guides are more than 10 year old though.

@AppVeyorBot
Copy link
Copy Markdown

See test results for failed build of commit c64e806ed6

@seanbudd seanbudd merged commit 7e21e3a into beta Dec 21, 2023
@seanbudd seanbudd deleted the fixupSyntax branch December 21, 2023 23:02
seanbudd added a commit that referenced this pull request Jan 9, 2024
Closes #8734
Part of #15014
Related nvaccess/nvda-misc-deps#30, #16002, #15950, #15939, #15981

Summary of the issue:
In order to migrate to Crowdin, we must convert txt2tags to markdown.
In order transition safely, beta will build docs from t2t to markdown to html.
Eventually the t2t will be removed and the markdown will become the source of truth.

Description of user facing changes
The user Guide no longer has numbered sections

Translators and documentation writers now use extended markdown syntax rather than txt2tags.

Description of development approach
The build system performs certain pre-processing and post-processing when converting t2t to HTML.
This equivalent system should be retained - i.e. the translator and documentation contribution experience should remain the same for markdown to HTML.
Additionally, when converting t2t to markdown, new processing rules had to be created.

There is no universal standard for custom anchors in markdown.
As such text2tags doesn't have default rules for this. To retain our custom anchors, I added rules for a common markdown extended syntax.
Similarly a shortcut is used for generating table of contents.
See nvaccess/nvda-misc-deps#30

Setting the language code is done using the user_docs folder name, and the direction of RTL is manually set for the 3 current languages that require it, Persian, Arabic, Hebrew.

Special Catalan processing for adding hreflang attributes is converted to a markdown extension syntax of {hreflang=en}

The key commands file is generated using a custom made markdown python extension.
Adriani90 pushed a commit to Adriani90/nvda that referenced this pull request Mar 13, 2024
Closes nvaccess#13333

Summary of the issue:
To aid with converting to markdown, fixing txt2tags syntax issues will ensure the conversion works as expected.
Note that not all syntax issues are fixed, however this PR intends to catch easy fixes that can be fixed with regex.
This may result in bad syntax in the markdown files, however these are syntax issues in the current documentation so conversion is unlikely to be a step in a worse direction.

Description of user facing changes
None

Description of development approach
Regex groups:

([^`])`([^`]) replaced with $1``$2
^ (  )*- to detect lists indented by an odd number of spaces
Unmaintained files in user_docs have been removed
Adriani90 pushed a commit to Adriani90/nvda that referenced this pull request Mar 13, 2024
Closes nvaccess#8734
Part of nvaccess#15014
Related nvaccess/nvda-misc-deps#30, nvaccess#16002, nvaccess#15950, nvaccess#15939, nvaccess#15981

Summary of the issue:
In order to migrate to Crowdin, we must convert txt2tags to markdown.
In order transition safely, beta will build docs from t2t to markdown to html.
Eventually the t2t will be removed and the markdown will become the source of truth.

Description of user facing changes
The user Guide no longer has numbered sections

Translators and documentation writers now use extended markdown syntax rather than txt2tags.

Description of development approach
The build system performs certain pre-processing and post-processing when converting t2t to HTML.
This equivalent system should be retained - i.e. the translator and documentation contribution experience should remain the same for markdown to HTML.
Additionally, when converting t2t to markdown, new processing rules had to be created.

There is no universal standard for custom anchors in markdown.
As such text2tags doesn't have default rules for this. To retain our custom anchors, I added rules for a common markdown extended syntax.
Similarly a shortcut is used for generating table of contents.
See nvaccess/nvda-misc-deps#30

Setting the language code is done using the user_docs folder name, and the direction of RTL is manually set for the 3 current languages that require it, Persian, Arabic, Hebrew.

Special Catalan processing for adding hreflang attributes is converted to a markdown extension syntax of {hreflang=en}

The key commands file is generated using a custom made markdown python extension.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove outdated translated developerGuide, or move to Crowdin (was: remove outdated files)

6 participants