Created attachment 179607 [details] Poor documentation layout Preface: I've been a web developer for over 15 years. I've read API docs from hundreds, possibly over a thousand of libraries and projects. LibreOffice is the most horribly organized API that I've seen, with the worst documentation that I've encountered. I'm really sorry to say this, but it's my honest opinion. To make this bug more concrete and actionable, I'll give some examples. 1. Five years since I've asked, there is still no clear reference documentation for the JavaScript macro API (https://ask.libreoffice.org/t/javascript-macro-reference/25851). Why does it even exist? 2. The documentation web page template at https://help.libreoffice.org/7.4/en-US/text/sbasic/shared/03/lib_tools.html has a pointlessly narrow column width, which truncates the visible text and makes it impossible to clearly see an entry at once (see screenshot). That text column also scrolls through the search bar at the top. 3. Searching through the macros documentation returns a jumble of results, mixing user-facing functions and Calc formulas. Try searching for "regular expression" in hopes of finding a BASIC macro function that does regular expression search and replace. Apparently there isn't one. 🤦 To use regular expressions, you need to import some cryptic service, and the code looks like this mess: 🤢 yourString = 'Some string with a cell reference like A123 and other stuff' oTextSearch = CreateUnoService("com.sun.star.util.TextSearch") oOptions = CreateUnoStruct("com.sun.star.util.SearchOptions") oOptions.algorithmType = com.sun.star.util.SearchAlgorithms.REGEXP oOptions.searchString = "([A-Z0-9]+)" oTextSearch.setOptions(oOptions) oFound = oTextSearch.searchForward(yourString, 0, Len(yourString)) sFound = mid(yourString, oFound.startOffset(0) + 1, oFound.endOffset(0) - oFound.startOffset(0)) MsgBox(sFound) (By the way, I found this on StackOverflow, not anywhere in the documentation. For 20+ years, the vast majority of programming languages have had built-in functions for regular expression search.) 4. The BASIC **Strings** module (https://help.libreoffice.org/7.4/en-US/text/sbasic/shared/03/lib_tools.html?&DbPAR=BASIC&System=UNIX#strings_module) lacks such basic functions as finding or replacing based on regular expressions. 🤦🏼♂️ Instead, it provides a **Power** function, which has absolutely nothing to do with strings, or a "CheckDouble" one, without documentation. 5. Apparently nobody has edited the documentation for comprehensible English. From the same page: "Retrieves the second value for a next to 'SearchString' in a two-dimensional string-Array" - what? 6. The documentation is apparently split up with some parts at help.libreoffice.org, and others at api.libreoffice.org (e.g. https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1util_1_1SearchDescriptor.html, which again is devoid of examples and context) I know there are probably historical arguments for why things are the way they are, but please understand that A NEW DEVELOPER DOESN'T CARE about this, and they will be turned off by the current state of the API and documentation. (I'm weird and have stuck with it for 5+ years, but for every person like me, 100 have just left without bothering to leave any feedback - see https://en.wikipedia.org/wiki/1%25_rule). So if we want to stop scaring away users and macro developers, we'd better fix this.
Re. 6 - some more documentation is split at documentation.libreoffice.org, such as this useful cheat sheet - https://documentation.libreoffice.org/assets/Uploads/Documentation/en/MACROS/RefCards/LibOBasic-3-Calc-Flat-A4-EN-v111.pdf Centralizing and cross-linking these disparate places would be a step forward, but a clean solution would be to bring all the documentation in *one* place, in an easily editable format *stored on GitHub*, using a modern documentation publishing framework like https://readthedocs.org/ or https://docusaurus.io/, or at least a Wiki like MediaWiki. I suspect a chunk of documentation might be in code comments and needs to be extracted out, so I'm not making specific recommendations for a documentation platform. But I do want to urge using GitHub (or at least GitLab) as the VCS, because whether you like it or not, GitHub does make it easy to edit documentation in a browser, and has the highest number of registered developers familiar with its interface and with an account already set up. This is key for encouraging "drive-by" documentation fixes and contributions. Note that MDN, one of the largest and most often accessed open-source documentation platforms ever, has also switched to GitHub for hosting the content and accepting contributions - https://hacks.mozilla.org/2020/10/mdn-web-docs-evolves-lowdown-on-the-upcoming-new-platform/
(In reply to Dan Dascalescu from comment #0) > 2. The documentation web page template at > https://help.libreoffice.org/7.4/en-US/text/sbasic/shared/03/lib_tools.html > has a pointlessly narrow column width, which truncates the visible text and > makes it impossible to clearly see an entry at once (see screenshot). That > text column also scrolls through the search bar at the top. The template is fine. It seems here the content creators have been a bit absentminded. A table was used to create additional layout, which wrecks mobile-friendliness. Also, the code blocks have pointless indentation that make the layout fail even on desktop. I can simplify the page and any others like it. Olivier can comment on the other stuff. I am pleased to say we have finally imported the old UNO API developer's guide into TDF wiki: https://wiki.documentfoundation.org/Documentation/DevGuide It is being updated.
1) Recent discussions in the ESC (Engineering Steering Commt'ee) lead to a phase-out of JavaBeans and JavaScript in the future. https://lists.freedesktop.org/archives/libreoffice/2022-January/088371.html Nevertheless, our documentation guides have some starting point for Javascript: https://books.libreoffice.org/en/GS73/GS7313-GettingStartedWithMacros.html#toc39 2) The poor layout is likely consequence of the update of prism.js and prism.css in master branch. Some tweak to set because the previous releases are not affected. https://gerrit.libreoffice.org/c/help/+/132570 3) It has been a looooong time like that and fixing it depends on volunteer effort or business investment on the issue. To give an example, we submitted (but were not picked for funding) a project on illustrating the API: https://wiki.documentfoundation.org/Documentation/GSoDOC/2022 And this project is an easy hack, actually. 4) These "Advanced" libraries are in the code since the birth of OpenOffice.org (StarOffice?) and were never documented. Excluding the current formatting issue, the Help page was an effort to give a minimum visibility of the macros. It worked since you got there (and your comments are appreciated) :-). 5) Exactly because reading the code is a time consuming task and the script signature has already a minimal useful information. The build of the Help page was done with a script and no human intervention. Feel free to propose a better, perhaps more professional description. Note a) the library is static from ages and is likely to stay like that unless you want to add contents and b) the script signatures are not translated. c) Have a look at the Scriptforge libraries under development at the moment. Documentation is coming along with the forge development. 6) Correct. These are 2 different entities. The Help targets the end user and the API targets developers and advanced script coders. Besides, the Help is translated into +70 languages while the API is not. Pushing for more contents to translation is something we consider with special care. The API website (which is an online version of the LibreOffice SDK) is generated by Doxygen. Of course, volunteers are welcome to improve the page layout and usability, as well as contents. Doxygen experts are welcome. Finally, the documentation is left historically to the community. We advise volunteers but we won't prevent them from using their pet tool for their own use. That said, some communities prefer wiki, others books, some Ask, other mailing list or Telegram groups, and so on... PS. we are aware of readthedocs and other tools in github.
First stab: https://gerrit.libreoffice.org/c/help/+/133096 Very much simplified. The old version had the table headers Macro Calling parameters and comments I just skipped them for now. Maybe Olivier has ideas on how to present the function names to make them stand out a bit. As headings?
Used variations of this theme for function names, find: <paragraph id="par_id([0-9]+)" role="paragraph" xml-lang="en-US" localize="false">([^\s]+)</paragraph> Replace: <h3 id="hd_id\1" xml-lang="en-US" localize="false">\2</h3>
While paying attention to the mobile-unfriendliness of elements, such as wide tables, I noticed pages like these have tables that would need additional CSS to make them responsive: https://help.libreoffice.org/7.4/en-US/text/sbasic/shared/03/lib_ScriptForge.html?DbPAR=BASIC "Services provided by the ScriptForge library" Just a note for myself.
Ilmari Lauhakangas committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/help/commit/24828f91e22842cdaf64faf7d22a028541e5746c tdf#148621 Improve Basic Help layout
Ilmari Lauhakangas committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/help/commit/5bab8a2d2530d7487064a2560c440269018a56b9 tdf#148621 Make ScriptForge service tables mobile-friendly