Recent

Author Topic: Dash documentation for Lazarus and FPC?  (Read 868 times)

vfclists

  • Hero Member
  • *****
  • Posts: 1146
    • HowTos Considered Harmful?
Dash documentation for Lazarus and FPC?
« on: September 19, 2024, 03:06:09 pm »
What will it take for the Lazarus and FPC help to be made compatible with Dash for macOS - API Documentation Browser, Snippet Manager - Kapeli, as described at Docset Generation Guide - Kapeli?

For Linux and Windows users there is Dash clone that provides the same functionality and uses the docsets Zeal - Offline Documentation Browser

Are any Lazarus users familiar with it?
Lazarus 3.0/FPC 3.2.2

dbannon

  • Hero Member
  • *****
  • Posts: 3156
    • tomboy-ng, a rewrite of the classic Tomboy
Re: Dash documentation for Lazarus and FPC?
« Reply #1 on: September 20, 2024, 02:16:46 am »
Is it any better (apart from being familiar) to what we have now ?

It sure covers the market, 190 docsets.  And Zeal is available in the Debian repos.

Davo
Lazarus 3, Linux (and reluctantly Win10/11, OSX Monterey)
My Project - https://github.com/tomboy-notes/tomboy-ng and my github - https://github.com/davidbannon

vfclists

  • Hero Member
  • *****
  • Posts: 1146
    • HowTos Considered Harmful?
Re: Dash documentation for Lazarus and FPC?
« Reply #2 on: September 21, 2024, 01:11:52 am »
Is it any better (apart from being familiar) to what we have now ?

It sure covers the market, 190 docsets.  And Zeal is available in the Debian repos.

Davo

It provides a single interface to all your help docs.

I'm also starting to use Emacs more and more in my FPC and Lazarus editing and it will also help there.
Lazarus 3.0/FPC 3.2.2

marcov

  • Administrator
  • Hero Member
  • *
  • Posts: 11833
  • FPC developer.
Re: Dash documentation for Lazarus and FPC?
« Reply #3 on: September 21, 2024, 12:04:56 pm »
It provides a single interface to all your help docs.

So does the currently CHM system, and nearly any other helpsystem pretends to be universal if other people would just convert the existing helps :-)

But anyway, it seems that dash needs special tags embedded in the html, so you are probably looking at adding a new fpdoc backend for the RTL/FCL/LCL docs. You can look at how the CHM backend wraps around the basic html backend for that.

The latex docs (prog/user/ref etc) are a bit harder, see the  fpcdocs/src/compilelatexchm.pp that mutates html generated from latex for CHM purposes.

Then finally there is the lazarus IDE help, and afaik it is only stored in the wiki, with no systematic available offline help, so somebody's else would have to explain the practicalities of that  (*)

(*) yes, there are tools to downloads part of them, and sometimes that is even rumoured to have worked, and sometimes not. I never saw it work.

Then finally there is integration into the IDE. I don't know much about that either, but afaik it is currently fairly static for the existing set, and you can't embed random docsets into the IDE. How easily that can be changed I however don't know, so I don't know if that is a showstopper or not.

Note that any system that has umpteen files per docset (like each html lemma stored in separate files) is a bad match for Windows and embedded systems like Dos. Probably all non *nix systems (either by direct genealogy or spiritually). The original reason for the html to chm conversion is minutes of installation time of the FPC docs on win9x machines, and half an hour on light weight dos machines due to the large amount of files.

Modern machines are a bit better, but unfortunately SSDs without cache handle writes of many small files rather badly, sometimes even worse than a harddisk.
« Last Edit: September 21, 2024, 01:38:26 pm by marcov »

MarkMLl

  • Hero Member
  • *****
  • Posts: 7884
Re: Dash documentation for Lazarus and FPC?
« Reply #4 on: September 21, 2024, 01:19:30 pm »
Obligatory xkcd: https://xkcd.com/927/

There's far more pressing things to be done with the documentation than converting it to yet-another semi-proprietary format, which no doubt only behaves "fast and reliably" on the original platform.

MarkMLl
MT+86 & Turbo Pascal v1 on CCP/M-86, multitasking with LAN & graphics in 128Kb.
Logitech, TopSpeed & FTL Modula-2 on bare metal (Z80, '286 protected mode).
Pet hate: people who boast about the size and sophistication of their computer.
GitHub repositories: https://github.com/MarkMLl?tab=repositories

wp

  • Hero Member
  • *****
  • Posts: 12409
Re: Dash documentation for Lazarus and FPC?
« Reply #5 on: September 21, 2024, 01:53:28 pm »
(*) yes, there are tools to downloads part of them, and sometimes that is even rumoured to have worked, and sometimes not. I never saw it work.
This is the batch file that I use to download the FPSpreadsheet wiki pages and convert them to chm:
Code: [Select]
echo off

rem set FMT=html
set FMT=chm
echo Downloading wiki...

wikiget --page=FPSpreadsheet --page=FPSpreadsheet:_Examples --page=FPSpreadsheet:_List_of_formulas --page=RPN_Formulas_in_FPSpreadsheet
wikiget --page=FPSpreadsheet:_Chart_Tutorial
wikiget --page=FPSpreadsheet_tutorial:_Writing_a_mini_spreadsheet_application
wikiget --page=TsWorksheetGrid --page=TsWorksheetChartSource

echo.
echo Converting wiki to chm...

wikiconvert --format=%FMT% --css=css/wiki.css --root="FPSpreadsheet wiki pages" --title="FPSpreadsheet wiki pages (offline version, created %DATE%)" --chm="..\fpspreadsheet-wiki.chm" wikixml/FPSpreadsheet.s00.xml wikixml/FPSpreadsheet=3A_Examples.s0300.xml wikixml/FPSpreadsheet=3A_List_of_formulas.s03000.xml wikixml/RPN_Formulas_in_FPSpreadsheet.u03g00.xml wikixml/FPSpreadsheet_tutorial=3A_Writing_a_mini_spreadsheet_application.s000c0000000.xml wikixml/TsWorksheetGrid.k08.xml wikixml/FPSpreadsheet=3A_Chart_Tutorial.s03100.xml

set FMT=

IIRC, however, there was an issue to find the Laz/FPC version  in which wikiconvert is working correctly. In the "instructions.txt" I had noted that only Laz 2.08/FPC 3.0.4 are working ("In later versions the contents page is not created correctly (tested up to Laz 2.2/fpc3.2.2)"

MarkMLl

  • Hero Member
  • *****
  • Posts: 7884
Re: Dash documentation for Lazarus and FPC?
« Reply #6 on: September 21, 2024, 02:44:07 pm »
So just to get that straight: wikiget and wikiconvert come with Lazarus. Where does FPSpreadsheet come from: is it a local file?

My experience when I've looked at this sort of thing in the past was that there was a great deal which was highly version-specific and that you really needed the same version of tools as were used with the version of CHM etc. accompanying a particular (FPC) release).  I ended up working from PDFs converted back to plain text, which introduces its own can of worms...

MarkMLl
MT+86 & Turbo Pascal v1 on CCP/M-86, multitasking with LAN & graphics in 128Kb.
Logitech, TopSpeed & FTL Modula-2 on bare metal (Z80, '286 protected mode).
Pet hate: people who boast about the size and sophistication of their computer.
GitHub repositories: https://github.com/MarkMLl?tab=repositories

marcov

  • Administrator
  • Hero Member
  • *
  • Posts: 11833
  • FPC developer.
Re: Dash documentation for Lazarus and FPC?
« Reply #7 on: September 21, 2024, 03:39:28 pm »
IIRC, however, there was an issue to find the Laz/FPC version  in which wikiconvert is working correctly. In the "instructions.txt" I had noted that only Laz 2.08/FPC 3.0.4 are working ("In later versions the contents page is not created correctly (tested up to Laz 2.2/fpc3.2.2)"

Single page gets, external sources of which page to get (and probably how to combine them). A rough start, but a start nonetheless.

Mass getting single pages iirc hits wiki security.
« Last Edit: September 21, 2024, 05:22:03 pm by marcov »

dsiders

  • Hero Member
  • *****
  • Posts: 1259
Re: Dash documentation for Lazarus and FPC?
« Reply #8 on: September 21, 2024, 05:59:58 pm »
So just to get that straight: wikiget and wikiconvert come with Lazarus. Where does FPSpreadsheet come from: is it a local file?

FPSpreadsheet is available on OPM.
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

dsiders

  • Hero Member
  • *****
  • Posts: 1259
Re: Dash documentation for Lazarus and FPC?
« Reply #9 on: September 21, 2024, 06:22:21 pm »
Then finally there is the lazarus IDE help, and afaik it is only stored in the wiki, with no systematic available offline help, so somebody's else would have to explain the practicalities of that  (*)

There are help contexts in the IDE that link to the wiki pages. The Help button on IDE Options dialogs are a good example.

Then finally there is integration into the IDE. I don't know much about that either, but afaik it is currently fairly static for the existing set, and you can't embed random docsets into the IDE. How easily that can be changed I however don't know, so I don't know if that is a showstopper or not.

CHM support in the IDE requires code which access the CHM help databases, It currently supports RTL, FCL, LCL and LazUtils. It requires the raw XML files for code help (which is why RTL/FCL are so limited ). I have not found a way to integrate an arbitrary 3rd-party CHM into the IDE. Trust me, I've tried.

You can integrate HTML help stored locally in docs/html, which I've done using the LazControls content from: https://dsiders.gitlab.io/lazdocsnext/lazcontrols/index.html. But even that is not exactly straight forward.

To me, it seems like one of those areas where "don't touch it" has been the adopted approach.

« Last Edit: September 21, 2024, 06:46:18 pm by dsiders »
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

marcov

  • Administrator
  • Hero Member
  • *
  • Posts: 11833
  • FPC developer.
Re: Dash documentation for Lazarus and FPC?
« Reply #10 on: September 21, 2024, 08:58:54 pm »
Then finally there is the lazarus IDE help, and afaik it is only stored in the wiki, with no systematic available offline help, so somebody's else would have to explain the practicalities of that  (*)

There are help contexts in the IDE that link to the wiki pages. The Help button on IDE Options dialogs are a good example.

I do understand that. Where is the list of files to download with wikiget (as WP showed) to create an offline IDE help ?

Quote
Then finally there is integration into the IDE. I don't know much about that either, but afaik it is currently fairly static for the existing set, and you can't embed random docsets into the IDE. How easily that can be changed I however don't know, so I don't know if that is a showstopper or not.

CHM support in the IDE requires code which access the CHM help databases, It currently supports RTL, FCL, LCL and LazUtils. It requires the raw XML files for code help (which is why RTL/FCL are so limited ).

That's bad. A solution must be found for that, if only it is packaging the XMLs into the CHMs.

Quote
I have not found a way to integrate an arbitrary 3rd-party CHM into the IDE. Trust me, I've tried.

You can integrate HTML help stored locally in docs/html, which I've done using the LazControls content from: https://dsiders.gitlab.io/lazdocsnext/lazcontrols/index.html. But even that is not exactly straight forward.

To me, it seems like one of those areas where "don't touch it" has been the adopted approach.

Not all Lazarus members were (are?) a fan of offline help.

Note that offline help is not just about providing help for people disconnected from the internet. It is also about versioning (having the help for an older version of Lazarus), as the WIKI is not really versioned.

dsiders

  • Hero Member
  • *****
  • Posts: 1259
Re: Dash documentation for Lazarus and FPC?
« Reply #11 on: September 21, 2024, 09:34:21 pm »
I do understand that. Where is the list of files to download with wikiget (as WP showed) to create an offline IDE help ?

I can't answer that. I suppose you could scour the IDE source code... but I've never see a list of URLs for those topics.

Quote
Quote
CHM support in the IDE requires code which access the CHM help databases, It currently supports RTL, FCL, LCL and LazUtils. It requires the raw XML files for code help (which is why RTL/FCL are so limited ).

That's bad. A solution must be found for that, if only it is packaging the XMLs into the CHMs.
[

They are separate FPDoc XML files located in docs/xml . For popup code help, the CHM plays no part.
« Last Edit: September 21, 2024, 09:36:00 pm by dsiders »
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

 

TinyPortal © 2005-2018