• Please review our updated Terms and Rules here

How to create (missing) man pages

Elektraglide

Elektraglide

Experienced Member
Joined
Mar 24, 2023
Messages
53
Location
UK
As I reverse engineer code on the Tek4404, I learn more about exact limits of commands, required formats etc etc.
Is there a simple way of generating documentation beyond just text files? Perhaps some nroff based thing?
I appreciate not a lot of people will be reading these but it seems right to capture the knowledge.

Adam
 
I'm sorry, did you not just ask if there was some nroff based thing?

There's always Wordpress.
 
Touche! Yes I didn't articulate that very well. I was asking if there is a tool that simplifies marking up text. I see emacs does have a roff mode that could help but I guess no getting around re-learning all those layout markers..
 
There are various tools to generate documentation (including manpages). For example, AsciiDoc can generate manpages, and this tool: https://drewdevault.com/2018/05/13/scdoc.html can create manpages from markdown-like text files. Of course, groff (the GNU implementation of troff / nroff) is still available everywhere.

It all depends on what you actually want to do, which you didn't say.
 
Svenska said:
It all depends on what you actually want to do, which you didn't say.
Click to expand...

The tek4404 has zero docs regarding anything network / sockets. Using Ghidra and other disassembly I have found that there is a number of functions that I wanted to document - for myself as much as others. eg pioctl() seems to be something a bit like ioctl() and setsockopt() and is used for promiscuous mode etc.
So wanting something I can markup some description and display in an expected way.

I'll get nroff installed on this Mac :)
 
Elektraglide said:
The tek4404 has zero docs regarding anything network / sockets. Using Ghidra and other disassembly I have found that there is a number of functions that I wanted to document - for myself as much as others. eg pioctl() seems to be something a bit like ioctl() and setsockopt() and is used for promiscuous mode etc.
So wanting something I can markup some description and display in an expected way.

I'll get nroff installed on this Mac :)
Click to expand...
The user land is BSD is that should be easy enough to do.

I can not understand why member with years *nix based system experience on this forum never suggested that.
 
Last edited:
What is incredibly confusing is that the system he's trying to figure out is running Uniflex, not Unix
If you look at https://github.com/Elektraglide/tek4404 it is not immediately obvious he's doing cross-development on a Mac

and the documents at

aren't unix man pages

the system was really intended to run Lisp or Smalltalk

snapshot of the TCP/IP install disk for the 4400
 

Attachments

  • 4400 ethernet.png
    4400 ethernet.png
    22.8 KB · Views: 4
Last edited:
the stack may have come from Tek
it doesn't look like TSC did one until 1989 and they only mention 020/030 not 010 in the 4404

--- strings inside install disk 2

Tek Version 2.4 @ 09:58:13 Wed Dec 17 1986
Copyright (C) 1985,1986 by Network Research Corporation, Inc.
all rights reserved.
Version 11.2 as of 86/01/29 at 08:01:35
wrapper.a,v 2.0 86/09/10 12:02:06 rich Released

---

may be based on Network Research "Fusion"
 

Attachments

  • fusion.png
    fusion.png
    124.8 KB · Views: 0
Last edited:
and... after all that digging I realized I didn't understand his question because I had to figure out the whole context of what he was asking.

yes, there are tools like nroff -man for making man pages, but...
why do you think you need to create a man page in the first place?

why can't you just write it as prose in a text file?
are there diagrams that need to be included?
would something written with man formatting be clearer somehow?
 
Al Kossow said:
would something written with man formatting be clearer somehow?
Click to expand...
Yes, that!
Of course I can continue scribbling notes in a text file. Just thought it would be better to structure the information a little.
If you're interested, the github repo below has a bunch of utilities I've written to make life saner with Uniflex.
https://github.com/Elektraglide/tek4404 (I do try and make them compile on a Mac also just so I can test on a known-good system)

My latest addition is I hated that the standard shell takes 350k per instance (on a machine with 2Mb). I looked at source for csh etc and they are many files and would require fighting the tek4404 cpp / compiler so I wrote a single file shell inC with no dependencies that runs in 35k and has history, command completion and command line editing. Needs a little more work but has cut down memory usage significantly.

https://github.com/Elektraglide/ash
 
Last edited:
Elektraglide said:
Yes, that!
Of course I can continue scribbling notes in a text file. Just thought it would be better to structure the information a little.
If you're interested, the github repo below has a bunch of utilities I've written to make life saner with Uniflex.
https://github.com/Elektraglide/tek4404 (I do try and make them compile on a Mac also just so I can test on a known-good system)

My latest addition is I hated that the standard shell takes 350k per instance (on a machine with 2Mb). I looked at source for csh etc and they are many files and would require fighting the tek4404 cpp / compiler so I wrote a single file shell inC with no dependencies that runs in 35k and has history, command completion and command line editing. Needs a little more work but has cut down memory usage significantly.

https://github.com/Elektraglide/ash
Click to expand...
Just so that you know, what you are doing is absolutely sick and I love it.
 
Working with *roff isn't that bad, but... I have a package where I used to distribute a man page with source, and a text file based on the man page with some (non-*nix) binary builds. As part of my Markdown mania, I switched them around, and now I build the man page with md2man-roff (after trying some other packages that did the same thing). The Markdown version is already readable as plain text.
 
Another similar option is using rst2man to generate man pages from reStructuredText (reST), which as far as I can tell is like markdown but seems to be just one fairly powerful standard, whereas markdown is a whole bunch of superficially similar languages with different limitations in each tool. Whenever someone says a tool supports markdown I can guess it probably supports bold, italics, headings and links, and beyond that I'll have to check its documentation to see what else it can do and will probably come out fairly disappointed.

An option I'd probably use is DocBook XML. It has support for generating man files - although I haven't tried that myself - along with HTML, PDF, and various other formats. It uses semantic markup and is incredibly expressive. Of course writing XML by hand in a plain text editor isn't very nice, so I used the Vex (Visual Editor for XML) plugin for Eclipse (but it was a long time ago so it was a much older, different version), which was partially WYSIWYG and reasonably nice. I have no idea what that plugin is like these days thoug. It's a reasonable amount of work to learn how DocBook works by itself though; markdown or reST are much simpler options. Also some people have serious reactions to the mere mention of the words XML and Eclipse :LOL:
 
The issue with modern markup languages - particularly, Markdown - is that they allow using HTML or some other embedded languages for things they don't provide themselves. Their main usecase involves being rendered within a modern web browser, and it shows. Depending on the document's complexity, the required tooling may just be a full browser engine.
 
You must log in or register to reply here.
Back
Top