Factor online documentation for all platforms

[nomennescio]

Due to Factor's nature, you cannot view platform specific help in the Browser if you're not running on the same platform. The online documentation on https://docs.factorcode.org does not show platform specific help for Windows. Please make online help available for all platforms.

[nomennescio]

Because the online help is the same as Factor's help, which is platform specific, for now make a work-around with copies for different platforms, accessible via different URLs.

[mrjbq7]

Before we change anything I don’t want all the duplicate help files making Google hard to search. Se we either have to fix up domains or links and mark not canonical or whatever webmaster tools need to be done. Same for old versions.  On May 9, 2024, at 1:15 AM, nomennescio @.***> wrote: Because the online help is the same as Factor's help, which is platform specific, for now make a work-around with copies for different platforms, accessible via different URLs.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: @.***>

[mrjbq7]

And should we have both 32 and 64 bit available also?On May 9, 2024, at 6:27 AM, John Benediktsson @.> wrote:Before we change anything I don’t want all the duplicate help files making Google hard to search. Se we either have to fix up domains or links and mark not canonical or whatever webmaster tools need to be done. Same for old versions.  On May 9, 2024, at 1:15 AM, nomennescio @.> wrote: Because the online help is the same as Factor's help, which is platform specific, for now make a work-around with copies for different platforms, accessible via different URLs.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: @.***>

[mrjbq7]

I think I’d be more in favor of a merge approach that squishes docs together from multiple platforms rather than 3 endpoints. But happy to discuss more.On May 9, 2024, at 1:15 AM, nomennescio @.***> wrote: Because the online help is the same as Factor's help, which is platform specific, for now make a work-around with copies for different platforms, accessible via different URLs.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: @.***>

[mrjbq7]

I reverted 66dc4a2f28553f8b7e4f5f2bcb07544eceb62479, which is not needed until we build three separate docs, upload them to the server, update the dns, and release -- and that presumes we don't end up with a different approach, see above.

[nomennescio]

I reverted 66dc4a2, which is not needed until we build three separate docs, upload them to the server, update the dns, and release -- and that presumes we don't end up with a different approach, see above.

OK, let's further discuss in here, to collect all arguments

[nomennescio]

I think I’d be more in favor of a merge approach that squishes docs together from multiple platforms rather than 3 endpoints. But happy to discuss more.

Squishing might be possible; it might be beneficial if we could add some support for that to the markup

[nomennescio]

We have several classes of situations to handle:

• platform specific vocabs that are only loaded per platform example: https://docs.factorcode.org/content/vocab-io.backend.windows.html

Not loaded
You must first load this vocabulary to browse its documentation and words.
USE: io.backend.windows

Files
Not loaded
You must first load this vocabulary to browse its documentation and words.
USE: io.backend.windows

Files
https://github.com/factor/factor/blob/master/basis/io/backend/windows/windows.factor

[ToxicFrog]

Setting aside the technical obstacles to actually doing so, I think it's worth looking at how Python handles this:

• one unified documentation tree
• if a vocabulary has platform-specific differences, these are mentioned in the documentation for the vocab as a whole and, where relevant, for individual words in it, e.g. shutil
• if a vocabulary is only available on a specific platform, it's clearly marked as such, e.g msvcrt

It's also worth looking at how it handles multiple versions: documentation for all versions is hosted on the website, using normal URL paths, and there is a javascript switcher in the top left to switch language version. Then, robots.txt is used to exclude old and prerelease versions from being indexed, so external searchers will always return the documentation for the current stable version, while keeping the older documentation available. This is a similar model to what sites like readthedocs use and, in my experience, works very well.

On the implementation side, my understanding is that the Factor documentation is generated by loading all vocabularies, then telling it to generate documentation, which leads to two immediate problems I can see:

• vocabularies that won't even load on unsupported platforms (as opposed to loading but not actually functioning correctly) are invisible unless you generate the docs from that platform, which means you now need to generate the docs once on each supported platform and then merge them. Fixing this probably requires a way to load a vocab in "docs-only" mode that bypasses host platform checks and whatnot.
• vocabulary documentation is generated in factor rather than via an external tool, which means the format of the generated documentation has changed over the years, which means that documentation for older vocabularies may need postprocessing to be usefully integrated into the site.

[mrjbq7]

I believe most documentation is the same across all platforms, with a few differences:

• symbols/words that are defined for one OS or architecture that are not on another
• symbols/words that are different on one OS or architecture versus another (for example OS-specific generic word implementations, struct differences between 32- and 64- bit).

It should be pretty easy to merge the documentation, adding the ones that are not defined and extending the vocabulary/word index.

It should also be possible to merge multiple documentation files for different OS by either:

1. per-OS or per-architecture TAB on the symbol page
2. copying the M: windows foo and M: unix foo definitions into the same implementation block of the foo word.

[mrjbq7]

It is possible this is easier to solve going forward than looking backward at previous releases. Aside from 0.99 (and maybe some codewars solutions in 0.98), I doubt anyone cares that much about older releases.

[ToxicFrog]

As someone who doesn't run HEAD, the differences between 0.99 (what I'm running) and 0.100pre (what's on the documentation site) have tripped me up a few times, and I suspect it's the same for anyone else installing from package manager rather than git. You're probably right about 0.98- though.

[mrjbq7]

I wonder if the docs website should default to the latest release instead of HEAD

On Fri, May 10, 2024 at 12:11 PM B. Kelly @.***> wrote:

As someone who doesn't run HEAD, the differences between 0.99 (what I'm running) and 0.100pre (what's on the documentation site) have tripped me up a few times, and I suspect it's the same for anyone else installing from package manager rather than git. You're probably right about 0.98- though.

— Reply to this email directly, view it on GitHub https://github.com/factor/factor/issues/2845#issuecomment-2105136872, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAF5A4M3ZICJKB3UQ3ROH3ZBULWFAVCNFSM6AAAAAA4JCZ6BOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMBVGEZTMOBXGI . You are receiving this because you commented.Message ID: @.***>

[ToxicFrog]

Under normal circumstances I'd say yes, default should always be latest release, but using HEAD seems to be much more common in Factor than in other language communities I'm familiar with, so here I'm not sure.