Skip to content

Conversation

@berniegp
Copy link

@berniegp berniegp commented Nov 4, 2025

Fixes links to the Sleigh documentation in documentation files such as docs/GhidraClass/Debugger/A4-MachineState.html#sleigh-expressions in the distribution. They currently point to Ghidra/Features/Decompiler/src/main/doc/sleigh.xml which doesn't exist, at least in my Windows 11.4.2 distribution. I presume that the intent is to point to docs/languages/html/sleigh.html instead which does exist.

I couldn't find any contribution guidelines for docs so I hope this PR is properly made. For instance I'm unsure why there's both an html and md version of each page, and if both need to be updated. Not clear either how docs/languages/html/sleigh.html appears as part of the build.

I'll put this in bold to make it clear: I haven't tested building the docs with this change.

@nsadeveloper789
Copy link
Contributor

So, this issue basically comes down to the locations of documentation in the repo vs. the locations of the same documentation in the distribution. I do wish there was a bit more consistency between the two.... Worse, the technologies, formats, and conventions used in our documentation vary depending on the intended purpose (courseware, help, developer docs, etc.), and also just the preferences of the authors.

That said, for the Debugger, we use Markdown and render it to HTML using Pandoc: see https://github.com/NationalSecurityAgency/ghidra/blob/d0280a0e81e203e266e8aed1ab597b0e60163629/GhidraDocs/GhidraClass/Debugger/Makefile. The Markdown is designed to be viewable on GitHub. We currently render the HTML and commit it to the repo, because we have not yet integrated that step into our Gradle build.

It's similar for the Sleigh documentation. I believe it's using Docbook, so the source is XML, which is rendered to HTML and also checked into the repo. The build scripts copy both (Debugger docs located in GhidraDocs/GhidraClass in the repo, and Sleigh docs located in Features/Decompiler) into the docs/ folder of the installation zip.

So, I'd like if the "source" forms all refer to the other source forms as located in the repo (so that clicking the links in GitHub takes you to the right place). The HTML forms ought to refer to the other HTML forms as located in the installation. To do this the Right Way (TM), I'd recommend using a Lua-based transformer for Pandoc. We currently do this to change MD refs to HTML refs within the Debugger tutorial: https://github.com/NationalSecurityAgency/ghidra/blob/d0280a0e81e203e266e8aed1ab597b0e60163629/GhidraDocs/GhidraClass/Debugger/links-to-html.lua. I imagine we can easily transforms paths in the same manner.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants