Convert the user guide to Markdown

[rfuest]

At the moment the user guide is a ODT file in the repo, which is also available as a PDF file on the SourceForge website. From previous issues on GitHub I suspect that some users don't know the user guide even exists. The link is easy to miss on the website and it is only linked from the Help menu in the macOS version.

My suggestion is to convert the user guide into Markdown and use a static website generator to generate an online version of the user guide. I've create a proof of concept conversion based on Material for MkDocs, which can be viewed at: http://gtkwave.rfuest.de. The source is available at: https://github.com/rfuest/gtkwave/tree/docs/docs

Advantages of this approach are IMO:

• Markdown is better suited to be handled by GIT than the binary ODT file. This will make it easier for others to contribute to the user guide and to review the changes in PRs.
• Setting up automatic deployment to GitHub Pages seems to be easy: https://squidfunk.github.io/mkdocs-material/publishing-your-site/#github-pages
• The proof of concept website is also intended to replace http://gtkwave.sourceforge.net/ Having only one website, which is automatically generated from the GIT repository, will make maintenance easier. The SF website could then be changed to redirect to the new gtkwave.github.io, like we recently discussed in the PR regarding the application ID.
• The generated website automatically supports modern web features like responsive design or syntax highlighting for code examples.

If we decide to use this approach the docs still need some formatting fixes and someone needs to go through the docs and remove some outdated parts, like compiling for GTK-1.2. But the proof of concept should give a good indication of what the website could look like.

[gtkwave]

That looks pretty good.  I think it's a good plan of action to take.

-Tony

On Wednesday, August 10, 2022, 12:11:13 AM EDT, Ralf Fuest ***@***.***> wrote:  

At the moment the user guide is a ODT file in the repo, which is also available as a PDF file on the SourceForge website. From previous issues on GitHub I suspect that some users don't know the user guide even exists. The link is easy to miss on the website and it is only linked from the Help menu in the macOS version.

My suggestion is to convert the user guide into Markdown and use a static website generator to generate an online version of the user guide. I've create a proof of concept conversion based on Material for MkDocs, which can be viewed at: http://gtkwave.rfuest.de. The source is available at: https://github.com/rfuest/gtkwave/tree/docs/docs

Advantages of this approach are IMO:

• Markdown is better suited to be handled by GIT than the binary ODT file.
  This will make it easier for others to contribute to the user guide and to review the changes in PRs.
• Setting up automatic deployment to GitHub Pages seems to be easy: https://squidfunk.github.io/mkdocs-material/publishing-your-site/#github-pages
• The proof of concept website is also intended to replace http://gtkwave.sourceforge.net/
  Having only one website, which is automatically generated from the GIT repository, will make maintenance easier. The SF website could then be changed to redirect to the new gtkwave.github.io, like we recently discussed in the PR regarding the application ID.
• The generated website automatically supports modern web features like responsive design or syntax highlighting for code examples.

If we decide to use this approach the docs still need some formatting fixes and someone needs to go through the docs and remove some outdated parts, like compiling for GTK-1.2. But the proof of concept should give a good indication of what the website could look like.

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

[rfuest]

How would you like to proceed with this? Do you want to keep the docs in the same repo or create another repo for the docs/website?

[umarcor]

I would strongly suggest to:

• Use Sphinx + MyST instead of MkDocs. Both solutions allow using markdown, however, Sphinx is more powerful with regard to cross-references, even across sites. Since Sphinx is the most used static site generator in the open source EDA community, it allows tighter cross-referencing to e.g. GHDL's docs. See intersphinx:
  • https://github.com/ghdl/ghdl/blob/master/doc/conf.py#L204-L210
  • https://github.com/chipsalliance/f4pga/blob/main/docs/conf.py#L172-L185
• Have the sources in the same repo, close to the tool sources, in order to keep them in sync. Use GitHub's Pages feature to host the resulting site in branch gh-pages. I can help with setting up CI.

[rfuest]

I've now updated the docs to use Sphinx and rebased the branch onto the new master branch. The docs still need some work and contain a few broken references or text like "on page XXX", which doesn't work in the HTML version. Especially the "Compiling and Installing GTKWave" section is pretty outdated.

I've attached a PDF version of the docs, which I spend zero time on to configure, but it already looks pretty good with the default settings: gtkwave.pdf

[gtkwave]

The docs look good.  That conversion went quite well.

-Tony

[FurryAcetylCoA]

Hello, @rfuest I am planning to working on this and have identified several potential tasks

• [ ] Replace all instances of on page XX with appropriate cross-references
• [ ] Revise index.md to more closely resemble the original documentation
• [ ] update Compiling and Installing GTKWave section
• [ ] Update GTKWave User Interface section. Potentially adding new screenshots
• [ ] Remove & Revise the outdated part

Additionally, I have a couple of questions:

• Has support for other wave formats been permanently removed from GTKWave, or is this change temporary?
• Will we continue to include the "Implementation of an Efficient Method for Digital Waveform Compression" section in the documentation?

Please let me know if there are any specific guidelines or additional requirements that I should follow.

[rfuest]

That's great, thanks for helping to finish the markdown version of the docs.

At the moment the docs should be based on the features in GTKWave LTS 3.3. Most users will use that branch of GTKWave and the docs should reflect that state. The updated docs will be a good base for the GTKWave 4 docs when it is closer to release.

update Compiling and Installing GTKWave section

This is one section where I would mention both branches of GTKWave. It should contain instructions on how to build GTKWave 3.3 using autotools and how to try a GTKWave 4 development build with meson.

Update GTKWave User Interface section. Potentially adding new screenshots

Yes, the screenshots need to be updated. Many screenshots in that chapter still use the old style interface and that hasn't been the default since 2008. The whole section about the "Toolbutton interface" can be removed from this chapter. While the old interface is technically still supported by GTKWave LTS no one uses it anymore.

Has support for other wave formats been permanently removed from GTKWave, or is this change temporary?

LXT, LXT2 and VZT are permanently removed from GTKWave 4. The loaders for formats that use a proprietary library are removed because I don't have access to the libraries and I'm unable to keep them working. Support for these formats will depend on external contributors that need these formats.

While this only applies to GTKWave 4 we could add a deprecation notice to the GTKWave 3.3 docs to let users know which formats won't be supported anymore in future versions of GTKWave. Perhaps with a note that they could open a GitHub issue if they require any of the removed formats.

Will we continue to include the "Implementation of an Efficient Method for Digital Waveform Compression" section in the documentation?

I wouldn't include this in the markdown docs and just link to a PDF version of that paper.

Please let me know if there are any specific guidelines or additional requirements that I should follow.

I don't have any guidelines at the moment, but please let me or Tony know if you need any questions.

[rfuest]

I've merged the unfinished docs into the master branch to make it easier to update the docs via PRs.

[umarcor]

In #338 I proposed a GitHub Actions workflow to build and deploy the docs to branch gh-pages.

Will we continue to include the "Implementation of an Efficient Method for Digital Waveform Compression" section in the documentation?

I wouldn't include this in the markdown docs and just link to a PDF version of that paper.

I would propose creating a repo for that article in this org (say github.com/gtkwave/dwc) and have the sources in LaTeX built to PDF in CI. I can help with that if you (@tbybell, @rfuest) agree.

[rfuest]

I would propose creating a repo for that article in this org (say github.com/gtkwave/dwc) and have the sources in LaTeX built to PDF in CI. I can help with that if you (@tbybell, @rfuest) agree.

I don't think that will be necessary, because the paper shouldn't change in the future and serving it as a static asset is enough. But it's Tony's paper and he should decide to handle it in the future.

[tbybell]

I'd say make it a static asset or just remove it. Less is more sometimes.

The main reason the paper is in there is because I was going to treat it as a conference submission for professional development requirements for work (look at the email address I used in it) way back in 2014, but except for one director who provided very good feedback to me, the other reviewers in my org who I bounced it off had no real expertise in that area to approve or disapprove it so the conference submission dropped on the floor and I found myself way too busy with writing RTL to want to pursue how to get a conference submission out of it. My motivation for the paper's incorporation into the user manual was more along the lines of, "I put some amount of effort into this, and the documentation for how this works is nowhere else, so why not just publish it as end matter in the user manual so it doesn't totally go to waste?" Users of gtkwave don't really need to know any of that information. The same goes for any of the documentation for internals for LXT. Interfacing information where it exists is fine. Detailed internals in a user's manual are overkill.