[9front] 9front Programmer's Manual

[9front] 9front Programmer's Manual

[Humm]

(Just for fun, I played around a little with the manual, changing it 
to a “9front Programmer’s Manual” (with actually functioning build 
system).  I haven’t changed the contents of the papers and didn’t do 
much with the man pages.  Files describing the changes and a tarball 
with the changed files are at /n/disk/humm/docs .)

I would like to know/discuss the future of the Plan 9 Programmer’s 
Manual in 9front.  Currently, besides changed man pages and the 
addition of the nupas paper, it still is the same as 4E’s manual.  As 
far as I know, the only versions of it in print are sl’s rainbow books 
(at which I haven’t looked yet).

What I think might be okay options are (1) deleting everything having 
to do with putting the papers and manual pages together to a big 
Programmer’s Manual for print, (2) replacing that mechanism by a new 
one for just the man pages (akin to the rainbow books, if I actually 
understand what’s in them), and (3) fixing it up for a two-volume 
9front Programmer’s Manual.  Additionally, I imagine papers could be 
updated for 9front (as if someone would actually do that).

So, what’s the situation?  Are there any plans other than continuing 
to let it rot?

-- 
Humm

Re: [9front] 9front Programmer's Manual

[qwx]

> What I think might be okay options are (1) deleting everything having 
> to do with putting the papers and manual pages together to a big 
> Programmer’s Manual for print, (2) replacing that mechanism by a new 
> one for just the man pages (akin to the rainbow books, if I actually 
> understand what’s in them), and (3) fixing it up for a two-volume 
> 9front Programmer’s Manual.  Additionally, I imagine papers could be 
> updated for 9front (as if someone would actually do that).
> 
> So, what’s the situation?  Are there any plans other than continuing 
> to let it rot?

Are you volunteering?  As with other things, people propose then do
nothing.  It's annoying and comes up again and again.  It's already
great that we have so many articles written in the fqa, wiki and
elsewhere, but it's a difficult and time-consuming job for any one
person.  I'm trying to help a little bit by working on parts of the
fqa but it's taking forever.  Others do too.

I doubt any contributions would ever be unwelcome.  A 9front
programmer's manual would be nice.  It would be great if you made
one.

Cheers,

qwx

Re: [9front] 9front Programmer's Manual

[qwx]

> Files describing the changes and a tarball with the changed
> files are at /n/disk/humm/docs .)

Also, I don't believe everyone here knows about or uses the
9p.zone[1] grid, so please include details on how to access your
files.

	; 9fs tcp!9p.zone!9991
	; lc /n/9p.zone!9991/humm/docs

Thanks,

qwx

[1] http://9p.zone/man

Re: [9front] 9front Programmer's Manual

[Humm]

> Are you volunteering?  As with other things, people propose then do 
> nothing.  It's annoying and comes up again and again.  It's already 
> great that we have so many articles written in the fqa, wiki and 
> elsewhere, but it's a difficult and time-consuming job for any one 
> person.  I'm trying to help a little bit by working on parts of the 
> fqa but it's taking forever.  Others do too.

I’m open for doing work on the manual.

> I doubt any contributions would ever be unwelcome.  A 9front 
> programmer's manual would be nice.  It would be great if you made 
> one.

We have one already.  With mostly fine man pages and some papers, some 
of them not quite up to date, with the potential of putting even more 
material in there.

I’m mostly talking about the framework around it, the “Programmer’s 
Manual” part, the title page and ToC, the notion of one manual.  And 
that, we already have (see tcp!9p.zone!9991 /humm/print.pdf).

If we do want to keep that, we could also migrate stuff from the FQA 
there or merge them completely or do whatever else with it.

-- 
Humm

Re: [9front] 9front Programmer's Manual

[ori]

Quoth Humm <hummsmith42@gmail.com>:
> 
> So, what’s the situation?  Are there any plans other than continuing 
> to let it rot?

Updates and fixes to manpages are always
welcome and applied regularly. Improving
and fixing the build system is also good.

But papers are papers. It seems strange
to modify them. I think for papers, it
makes most sense to add a 'changes since
publication' document.

I'd also like more tutorial or 'theory of
operation' style docs that supplement the
manpages, and show how parts of the system
fit together, but I'm not much of a writer,
and haven't put much thought into this.

Re: [9front] 9front Programmer's Manual

[Stanley Lieber]

>  Additionally, I imagine papers could be updated for 9front (as if someone would actually do that).
> 
> So, what’s the situation?  Are there any plans other than continuing to let it rot?

those papers have bylines, and those authors haven’t expressed interest.

what specific changes did you have in mind, and what is the purpose of the exercise?

i split the man pages into separate books for print because the total page count was too large for amazon’s print on demand service.

sl

Re: [9front] 9front Programmer's Manual

[Stuart Morrow]

On 06/08/2021, ori@eigenstate.org <ori@eigenstate.org> wrote:
> Updates and fixes to manpages are always
> welcome and applied regularly.

ಠ_ಠ

Re: [9front] 9front Programmer's Manual

[Stuart Morrow]

On 06/08/2021, Stanley Lieber <sl@stanleylieber.com> wrote:
> what specific changes did you have in mind, and what is the purpose of the
> exercise?

Not OP, but looking at the (real-life) 10e manual, alot of the
one-page entries seem like no accident.

Gre(1) should be printed out and framed. It's absolutely beautiful.

Re: [9front] 9front Programmer's Manual

[sirjofri]

06.08.2021 17:05:30 ori@eigenstate.org:
> Quoth Humm <hummsmith42@gmail.com>:
>>
>> So, what’s the situation?  Are there any plans other than continuing
>> to let it rot?
>
> Updates and fixes to manpages are always
> welcome and applied regularly. Improving
> and fixing the build system is also good.
>
> But papers are papers. It seems strange
> to modify them. I think for papers, it
> makes most sense to add a 'changes since
> publication' document.

Absolutely, maybe as an appendix to the other documents or to the whole 
collection.

> I'd also like more tutorial or 'theory of
> operation' style docs that supplement the
> manpages, and show how parts of the system
> fit together, but I'm not much of a writer,
> and haven't put much thought into this.

Some people started writing stuff for the wiki, also the fqa contains 
some info (eg. Upas theory). I planned to write some papers about that 
when I had more time, but then I didn't have that time...

Personally, I like writing, although my language might not be sufficient.

Slightly offtopic, but I made pdf versions of the man pages available on 
my 9front public web server, especially for ereaders. I generally wanted 
to mirror some stuff.

sirjofri

Re: [9front] 9front Programmer's Manual

[Humm]

> what specific changes did you have in mind, and what is the purpose 
> of the exercise?

I had in mind either fixing and updating the means of building big 
volumes containing the documents and the man pages or removing them 
completely.

Building those big volumes probably wouldn’t actually be too useful, 
since it’s easy to read everything on-line.  It might help with 
reading stuff with, say, an e-book reader (as sirjofri mentioned), but 
even then stuff like title pages, a ToC, prefaces, and maybe even the 
permuted index wouldn’t have any purpose.

If the manual is to be printed, for whatever reason (like people 
finding it easier to read stuff on paper), as you currently do with 
one half of it, I like to have the means of building the print edition 
(a generic one, without colorful covers and custom page size 
adjustments) in the system.

As it is, we have a build system for big volumes somewhat usable for 
print, but it refers to Plan 9 4E on the title pages and in the first 
preface, doesn’t work well, and produces bad results (mix of troff 
default 8.5*11i and ms default 8*11i) without easy means to customize 
the page layout and type.  Whatever the outcome is, I don’t want to 
keep something bad like that.

Updating the documents or adding new ones is not a primary concern of 
mine here and can be done either way.

What I have done is create a working version of that, my 
/n/tcp!9p.zone!9991/humm/^(print.pdf docs) .  No big changes of 
content, just the name “9front Programmer’s Manual,” better page 
numbering, and easier control of parameters of the final result.

-- 
Humm

Re: [9front] 9front Programmer's Manual

[Stuart Morrow]

On 06/08/2021, ori@eigenstate.org <ori@eigenstate.org> wrote:
> Updates and fixes to manpages are always
> welcome and applied regularly. Improving
> and fixing the build system is also good.
>
> But papers are papers. It seems strange
> to modify them. I think for papers, it
> makes most sense to add a 'changes since
> publication' document.

Richard Miller's RISC-V stuff adds to asm.ms, for what it's worth.

But then that isn't really a paper.