* On 2022 23 Feb 10:46 -0600, Nick Craig-Wood wrote: > As a new user (new to both contesting and tlf) I was thinking about helping > with the docs too.
Welcome! > I think it would be good for the project to have nice looking online docs. > In another project I'm involved in (rclone) we use markdown for the docs and > convert that into man pages and the website. Forgive me! I have become somewhat of a man page purist in recent years. While I understand the utility of a single source file for all documentation, the fact is that while man pages are documentation they exist in a different problem domain than Web pages or a PDF manual. The existing man page is a pretty good reference even if it is a bit verbose, though that is a trend for many man pages these days. The HTML pages, though old, have the benefit of the screenshots of the Tlf UI. IMHO, Markdown is an ideal source format for the HTML and PDF documentation simply because it handles inline images in those formats. The way one approaches writing a manual with images seems much different than writing for the man page reference format where images cannot be used inline. > The website is the primary documentation method, but all the > information is in the man page too. I like this way of working because > there is only one source for the documentation - the markdown files - > and everything else is built from there. I could certainly help with > this if people thought it was a good idea. I'm not much of a technical > writer, but I'm a better software developer ;-) As I see it, the man page should be a reference that serves as a memory refresher for configuration and operation commands. The HTML/PDF should be a more conversational manual that makes use of the images and links. The man page can be output to HTML as well and included if desired in an HTML/PDF manual. These are just my thoughts. The rest of the project members likely have differing opinions! :-) > I just want to say thank you to all the developers of tlf - I know how > hard Open Source software is! You're welcome! I am only a hobbyist in the software realm so I don't know whether this is more difficult than closed source software or not. I do know that collaboration is fun and satisfying. 73, Nate -- "The optimist proclaims that we live in the best of all possible worlds. The pessimist fears this is true." Web: https://www.n0nb.us Projects: https://github.com/N0NB GPG fingerprint: 82D6 4F6B 0E67 CD41 F689 BBA6 FB2C 5130 D55A 8819
signature.asc
Description: PGP signature