Possible bug report: URL capitalization in online manual

Possible bug report: URL capitalization in online manual

[Ori Barbut]

[-- Attachment #1: Type: text/plain, Size: 648 bytes --]

It seems that sometime in the past week the capitalization scheme of URLs
generated for the online manual has changed. For example I see as
of 2020-02-02 per the cache on Bing, the following url worked:
https://orgmode.org/manual/Structure-of-code-blocks.html

The new URL is:
https://orgmode.org/manual/Structure-of-Code-Blocks.html

This seems to be true for many urls with title capitalization, some other
examples:
https://orgmode.org/manual/Column-view.html
https://orgmode.org/manual/Sparse-trees.html

Not sure if this was intentional? If so would it make sense to alias the
old URLs for people who have linked to the manual over the years?

[-- Attachment #2: Type: text/html, Size: 1028 bytes --]

Re: Possible bug report: URL capitalization in online manual

[Bastien]

Hi Ori,

Ori Barbut <ori@oribarbut.com> writes:

> Not sure if this was intentional?

Yes -- old html manual pages where still around and I deleted them,
because they confused people.

> If so would it make sense to alias the old URLs for people who have
> linked to the manual over the years?

Yes, such aliases would make sense at the web server level.

Can you track back on when the new scheme has been output when
exporting the manual and provide an alias list I should add to
the web server?

That would really help a lot!

Thanks,

-- 
 Bastien

Re: Possible bug report: URL capitalization in online manual

[Ori]

[-- Attachment #1: Type: text/plain, Size: 1040 bytes --]

I'm not sure which repo this all lives in but I believe since information
has been added to the paths, this should be easy. The other direction would
be trickier and would need the old scheme.

Wherever the current filename has capital letters after the first
character, make an alias using the sentence-case version.

Happy to take a stab at this if you can point me to the repo!

Ori

On Sat, Feb 8, 2020 at 2:15 PM Bastien <bzg@gnu.org> wrote:

> Hi Ori,
>
> Ori Barbut <ori@oribarbut.com> writes:
>
> > Not sure if this was intentional?
>
> Yes -- old html manual pages where still around and I deleted them,
> because they confused people.
>
> > If so would it make sense to alias the old URLs for people who have
> > linked to the manual over the years?
>
> Yes, such aliases would make sense at the web server level.
>
> Can you track back on when the new scheme has been output when
> exporting the manual and provide an alias list I should add to
> the web server?
>
> That would really help a lot!
>
> Thanks,
>
> --
>  Bastien
>

[-- Attachment #2: Type: text/html, Size: 1555 bytes --]

Re: Possible bug report: URL capitalization in online manual

[Bastien]

Hi Ori,

Ori <ori@oribarbut.com> writes:

> I'm not sure which repo this all lives in but I believe since
> information has been added to the paths, this should be easy. The
> other direction would be trickier and would need the old scheme.
>
> Wherever the current filename has capital letters after the first
> character, make an alias using the sentence-case version.
>
> Happy to take a stab at this if you can point me to the repo!

Thanks a lot for your help!

https://code.orgmode.org/bzg/org-mode/ is where doc/org-manual.org
lives.

By exporting the manual with ~$ make html and bisecting from Org's
repository, you may find the list of aliases that I can add.

I searched nginx docs on how to make URL matching case-insensible:
from what I understand, you can rewrite a case-sensibility-ignored
URL to another URL, but you cannot completely ignore case-sensibility.

If I am wrong, please let me know.

-- 
 Bastien

Re: Possible bug report: URL capitalization in online manual

[Ori]

[-- Attachment #1.1: Type: text/plain, Size: 2047 bytes --]

Hi Bastien,

Attached are the relevant URL aliases.

When I initially saw the issue I thought it was a matter of a change to the
way the docs are built, not old vs new documentation. That makes the list
I've attached a little tricky to maintain. Of course within emacs is the
best way for a user to reach the documentation, but maybe a different
approach for the web would be appropriate. Some ideas:

Versioned folders living side-by-side. That's done in some other projects
like Django, CommonMark, Bootstrap. A script could go into files from the
last version and indicate that these are docs for an older version of Org.

Keep aliasing. Require an alias added each time is removed or is renamed.
The script here would be a check between versions. Seems like more friction
both in creating the check and in requiring the aliases, though big
rearranges don't seem to be the norm so perhaps it's not so bad.

Just leave it. The easy option!

Maybe there are others.

At any rate, thanks for your help.

Ori

On Sat, Feb 8, 2020 at 2:56 PM Bastien <bzg@gnu.org> wrote:

> Hi Ori,
>
> Ori <ori@oribarbut.com> writes:
>
> > I'm not sure which repo this all lives in but I believe since
> > information has been added to the paths, this should be easy. The
> > other direction would be trickier and would need the old scheme.
> >
> > Wherever the current filename has capital letters after the first
> > character, make an alias using the sentence-case version.
> >
> > Happy to take a stab at this if you can point me to the repo!
>
> Thanks a lot for your help!
>
> https://code.orgmode.org/bzg/org-mode/ is where doc/org-manual.org
> lives.
>
> By exporting the manual with ~$ make html and bisecting from Org's
> repository, you may find the list of aliases that I can add.
>
> I searched nginx docs on how to make URL matching case-insensible:
> from what I understand, you can rewrite a case-sensibility-ignored
> URL to another URL, but you cannot completely ignore case-sensibility.
>
> If I am wrong, please let me know.
>
> --
>  Bastien
>

[-- Attachment #1.2: Type: text/html, Size: 2886 bytes --]

[-- Attachment #2: org-documentation-url-aliases.el --]
[-- Type: text/x-emacs-lisp, Size: 9349 bytes --]

;; /guide/ url aliases, (currentFile . oldFile)
(("ASCII_002fUTF_002d8-Export.html" . "ASCII_002fLatin_002d1_002fUTF_002d8-export.html")
 ("Agenda-Commands.html" . "Agenda-commands.html")
 ("Agenda-Dispatcher.html" . "Agenda-dispatcher.html")
 ("Agenda-Files.html" . "Agenda-files.html")
 ("Breaking-Down-Tasks.html" . "Breaking-down-tasks.html")
 ("Built_002din-Agenda-Views.html" . "Built_002din-agenda-views.html")
 ("Capture-Refile-Archive.html" . "Capture-_002d-Refile-_002d-Archive.html")
 ("Clocking-Work-Time.html" . "Clocking-work-time.html")
 ("Comment-Lines.html" . "Comment-lines.html")
 ("Creating-Timestamps.html" . "Creating-timestamps.html")
 ("Custom-Agenda-Views.html" . "Custom-agenda-views.html")
 ("Deadlines-and-Scheduling.html" . "Deadlines-and-scheduling.html")
 ("Emphasis-and-Monospace.html" . "Emphasis-and-monospace.html")
 ("Export-Settings.html" . "Export-options.html")
 ("External-Links.html" . "External-links.html")
 ("Global-TODO-List.html" . "Global-TODO-list.html")
 ("HTML-Export.html" . "HTML-export.html")
 ("Handling-Links.html" . "Handling-links.html")
 ("Include-Files.html" . "Include-files.html")
 ("LaTeX-Export.html" . "LaTeX-and-PDF-export.html")
 ("Matching-Tags-and-Properties.html" . "Matching-tags-and-properties.html")
 ("Multi_002dstate-Workflow.html" . "Multi_002dstate-workflows.html")
 ("Plain-Lists.html" . "Plain-lists.html")
 ("Progress-Logging.html" . "Progress-logging.html")
 ("Refile-and-Copy.html" . "Refile-and-copy.html")
 ("Search-View.html" . "Search-view.html")
 ("Setting-up-capture.html" . "Setting-up-a-capture-location.html")
 ("Sparse-Trees.html" . "Sparse-trees.html")
 ("Structure-Editing.html" . "Structure-editing.html")
 ("Table-of-Contents.html" . "Table-of-contents.html")
 ("The-Export-Dispatcher.html" . "The-export-dispatcher.html")
 ("Visibility-Cycling.html" . "Visibility-cycling.html")
 ("Working-with-Source-Code.html" . "Working-With-Source-Code.html")
 ("iCalendar-Export.html" . "iCalendar-export.html"))

;; /manual/ url aliases, (currentFile . oldFile)
(("Add_002don-Packages.html" . "Add_002don-packages.html")
 ("Adding-Export-Back_002dends.html" . "Adding-export-back_002dends.html")
 ("Adding-Hyperlink-Types.html" . "Adding-hyperlink-types.html")
 ("Advanced-Export-Configuration.html" . "Advanced-configuration.html")
 ("Agenda-Column-View.html" . "Agenda-column-view.html")
 ("Agenda-Commands.html" . "Agenda-commands.html")
 ("Agenda-Dispatcher.html" . "Agenda-dispatcher.html")
 ("Agenda-Files.html" . "Agenda-files.html")
 ("Agenda-Views.html" . "Agenda-views.html")
 ("Batch-Execution.html" . "Batch-execution.html")
 ("Beamer-Export.html" . "Beamer-export.html")
 ("Breaking-Down-Tasks.html" . "Breaking-down-tasks.html")
 ("Built_002din-Agenda-Views.html" . "Built_002din-agenda-views.html")
 ("Built_002din-Table-Editor.html" . "Built_002din-table-editor.html")
 ("Clean-View.html" . "Clean-view.html")
 ("Clocking-Work-Time.html" . "Clocking-work-time.html")
 ("Code-Evaluation-Security.html" . "Code-evaluation-security.html")
 ("Column-Groups.html" . "Column-groups.html")
 ("Column-View.html" . "Column-view.html")
 ("Column-Width-and-Alignment.html" . "Column-width-and-alignment.html")
 ("Comment-Lines.html" . "Comment-lines.html")
 ("Creating-Footnotes.html" . "Footnotes.html")
 ("Creating-Timestamps.html" . "Creating-timestamps.html")
 ("Custom-Agenda-Views.html" . "Custom-agenda-views.html")
 ("Custom-Searches.html" . "Custom-searches.html")
 ("Dates-and-Times.html" . "Dates-and-times.html")
 ("Deadlines-and-Scheduling.html" . "Deadlines-and-scheduling.html")
 ("Document-Structure.html" . "Document-structure.html")
 ("Dynamic-Blocks.html" . "Dynamic-blocks.html")
 ("Editing-Source-Code.html" . "Editing-source-code.html")
 ("Effort-Estimates.html" . "Effort-estimates.html")
 ("Emphasis-and-Monospace.html" . "Emphasis-and-monospace.html")
 ("Evaluating-Code-Blocks.html" . "Evaluating-code-blocks.html")
 ("Export-Settings.html" . "Export-settings.html")
 ("Export-in-Foreign-Buffers.html" . "Export-in-foreign-buffers.html")
 ("Exporting-Agenda-Views.html" . "Exporting-agenda-views.html")
 ("Exporting-Code-Blocks.html" . "Exporting-code-blocks.html")
 ("External-Links.html" . "External-links.html")
 ("Extracting-Agenda-Information.html" . "Extracting-agenda-information.html")
 ("Extracting-Source-Code.html" . "Extracting-source-code.html")
 ("Frames-and-Blocks-in-Beamer.html" . "Sectioning-Frames-and-Blocks-in-Beamer.html")
 ("HTML-Export.html" . "HTML-export.html")
 ("HTML-export-commands.html" . "HTML-Export-commands.html")
 ("HTML-specific-export-settings.html" . "HTML-Specific-export-settings.html")
 ("Handling-Links.html" . "Handling-links.html")
 ("History-and-Acknowledgments.html" . "History-and-acknowledgments.html")
 ("Horizontal-Rules.html" . "Horizontal-rules.html")
 ("In_002dbuffer-Settings.html" . "In_002dbuffer-settings.html")
 ("Include-Files.html" . "Include-files.html")
 ("Internal-Links.html" . "Internal-links.html")
 ("Key-bindings-and-Useful-Functions.html" . "Key-bindings-and-useful-functions.html")
 ("LaTeX-Export.html" . "LaTeX-export.html")
 ("LaTeX-math-snippets.html" . "Working-with-LaTeX-math-snippets.html")
 ("LaTeX_002fPDF-export-commands.html" . "LaTeX-export-commands.html")
 ("Link-Abbreviations.html" . "Link-abbreviations.html")
 ("Link-Format.html" . "Link-format.html")
 ("Literal-Examples.html" . "Literal-examples.html")
 ("Macro-Replacement.html" . "Macro-replacement.html")
 ("Markdown-Export.html" . "Markdown-export.html")
 ("Markup-for-Rich-Contents.html" . "Markup.html")
 ("MathML-and-OpenDocument-formula-files.html" . "Working-with-MathML-or-OpenDocument-formula-files.html")
 ("Noweb-Reference-Syntax.html" . "Noweb-reference-syntax.html")
 ("OpenDocument-Text-Export.html" . "OpenDocument-Text-export.html")
 ("Org-Crypt.html" . "org_002dcrypt.html")
 ("Org-Export.html" . "Org-export.html")
 ("Org-Mobile.html" . "MobileOrg.html")
 ("Org-Plot.html" . "Org_002dPlot.html")
 ("Org-Syntax.html" . "Org-syntax.html")
 ("Orgtbl-Mode.html" . "Orgtbl-mode.html")
 ("Other-Built_002din-Back_002dends.html" . "Other-built_002din-back_002dends.html")
 ("Plain-Lists.html" . "Plain-lists.html")
 ("Presentation-and-Sorting.html" . "Presentation-and-sorting.html")
 ("Progress-Logging.html" . "Progress-logging.html")
 ("Properties-and-Columns.html" . "Properties-and-columns.html")
 ("Property-Inheritance.html" . "Property-inheritance.html")
 ("Property-Searches.html" . "Property-searches.html")
 ("Property-Syntax.html" . "Property-syntax.html")
 ("Pulling-from-the-mobile-application.html" . "Pulling-from-MobileOrg.html")
 ("Pushing-to-the-mobile-application.html" . "Pushing-to-MobileOrg.html")
 ("RSS-Feeds.html" . "RSS-feeds.html")
 ("Radio-Targets.html" . "Radio-targets.html")
 ("Refile-and-Copy.html" . "Refile-and-copy.html")
 ("Refiling-and-Archiving.html" . "Capture-_002d-Refile-_002d-Archive.html")
 ("Results-of-Evaluation.html" . "Results-of-evaluation.html")
 ("Sample-Configuration.html" . "Sample-configuration.html")
 ("Search-Options.html" . "Search-options.html")
 ("Setting-Tags.html" . "Setting-tags.html")
 ("Site-map.html" . "Sitemap.html")
 ("Sorting-of-agenda-items.html" . "Sorting-agenda-items.html")
 ("Sparse-Trees.html" . "Sparse-trees.html")
 ("Special-Agenda-Views.html" . "Special-agenda-views.html")
 ("Special-Properties.html" . "Special-properties.html")
 ("Special-Symbols.html" . "Special-symbols.html")
 ("Speed-Keys.html" . "Speed-keys.html")
 ("Speeding-Up-Your-Agendas.html" . "Speeding-up-your-agendas.html")
 ("Structure-Editing.html" . "Structure-editing.html")
 ("Structure-of-Code-Blocks.html" . "Structure-of-code-blocks.html")
 ("Subscripts-and-Superscripts.html" . "Subscripts-and-superscripts.html")
 ("TODO-Basics.html" . "TODO-basics.html")
 ("TODO-Extensions.html" . "TODO-extensions.html")
 ("TODO-Items.html" . "TODO-items.html")
 ("TTY-Keys.html" . "TTY-keys.html")
 ("Table-of-Contents.html" . "Table-of-contents.html")
 ("Tables-in-Arbitrary-Syntax.html" . "Tables-in-arbitrary-syntax.html")
 ("Tag-Hierarchy.html" . "Tag-hierarchy.html")
 ("Tag-Inheritance.html" . "Tag-inheritance.html")
 ("Tag-Searches.html" . "Tag-searches.html")
 ("Texinfo-Export.html" . "Texinfo-export.html")
 ("The-Export-Dispatcher.html" . "The-export-dispatcher.html")
 ("The-Spreadsheet.html" . "The-spreadsheet.html")
 ("The-Very-Busy-C_002dc-C_002dc-Key.html" . "The-very-busy-C_002dc-C_002dc-key.html")
 ("The-capture-protocol.html" . "capture-protocol.html")
 ("The-open_002dsource-protocol.html" . "open_002dsource-protocol.html")
 ("The-store_002dlink-protocol.html" . "store_002dlink-protocol.html")
 ("Triggering-Publication.html" . "Triggering-publication.html")
 ("Uploading-Files.html" . "Uploading-files.html")
 ("Using-Header-Arguments.html" . "Using-header-arguments.html")
 ("Using-Links-Outside-Org.html" . "Using-links-outside-Org.html")
 ("Using-multiple-TBLFM-lines.html" . "Using-multiple-_0023_002bTBLFM-lines.html")
 ("Using-the-Mapping-API.html" . "Using-the-mapping-API.html")
 ("Using-the-Property-API.html" . "Using-the-property-API.html")
 ("Visibility-Cycling.html" . "Visibility-cycling.html")
 ("Working-with-Source-Code.html" . "Working-with-source-code.html")
 ("Working-with-Source-Code.html" . "Working-with-source-code.html")
 ("iCalendar-Export.html" . "iCalendar-export.html"))

Re: Possible bug report: URL capitalization in online manual

[Bastien]

Hi Ori,

thanks a lot for taking the trouble to produce this file, very useful.

I've now installed the rewrite rules on the server and all these links
are redirecting correctly. Given the amount of Org documentation links
living out there, that's really a good idea.

> Versioned folders living side-by-side.

I've thought about this, but I think it is too much. If someone thinks
otherwise, anyone can volunteer to maintain multiple versions of the
documentation on the website.

Thanks again!

-- 
 Bastien