Documentation is all Microsoft Word and thus hard to read online #431
Comments
|
Probably not. That was actually done a while ago (using RST I think) but ended up being rejected. I forget what the discussion was. |
|
That's pretty sad. The documentation is de facto binary blobs and thus pretty hard to maintain as it is; there's no way to do pull requests to patch problems. |
|
I would be most interested in knowing why pmetzger's suggestion was rejected, because on the face of it it seems an eminently sensible and useful one. |
|
The request to switch from Microsoft *.DOC or the newer *.DOCX formats to something else has come up in the past. No solution is nearly universally agreed upon anywhere. They all have issues. As Paul K points out, this topic gets tossed about occasionally. One thing the project has tried to be is as neutral as it can be when it makes sense. So, requiring a specific compiler or development environment has tended to be shied away. That said, when Bob started the project, he took (and continues to take) the make it easy on the writer's view. Since Word was what he had, that's what he used. But as Perry notes, Microsoft formats have never been source code control friendly. The core issue is that source control systems, like Git or the like, have to treat them as blobs (which is contentious I'll not open that issue any further). Document formats such as Markup, RST, and JavaDoc can solve source control problems. Still, the troff and tex document compilers families can work with source control just as well and have the advantage of being portable and running on many emulated systems. From a tool standpoint, besides the format issue, another negative of using either *.DOC and *.DOCX is that they are only supported by Microsoft and Apple as development vehicles. The other formats I mentioned have the advantage of being well supported on most, if not all, of the chosen development platforms, but the tools to use them vary widely (at least troff and tex allow you to use vi/emac or whatever text editor the writer wants to use). More importantly, many of the content creators, such as Bob and Rich, are using tools like Word, which, while many users are happy with tool X or Y, you will have a hard time finding ones that are universal to all of our target development environments, meets the source control criteria and is something that the content creators are willing to use. Plus ... as Perry mentioned, one of the biggest stumbling blocks if we change is getting from one format to another - which is a big job. That said ... Bob has observed that since the origin of many of the documents in the 1990s, the good news is that all of them should be able to be supported by LibreOffice. Rich Cornwell, another of the primary simulator authors and content creators, believes that all the *.DOC files will open with it, and we can create PDFs with the same. Besides being supported by all of MacOS, Windows, and Linux, since LibreOffice's native format of "flat odt" (.fodt) files is based on textual XML, it is known to be friendly to all of the currently available source control systems, they need not be stored as blobs. A quick poll of many of the core developers has said that, while they use Word/Pages/XXXX, they could probably live with LibreOffice - but only if it could be shown to work. So, I offer the following multi-step approach. I think the Steering Group would consider a change in the build processes to create PDFs with LibreOffice on all three development platforms as part of the build if it notes that you have >>optionally<< installed LibreOffice. That means the build scripts must be more intelligent (i.e., do no harm) than they are now. However, if the build script running on the local system can find a proper version of LibreOffice, it will also create the PDFs as an output. Perry, if you would like to offer scripts for each (Mac, Linux, Windows) and help us check to ensure that PDFs are reasonable, while I am one voice as it were, I do expect that such an offering would be well received by the SG, as it seems like it would bring us least amount of breakage with the large gain/removal of all the current major issues with the current format. Once that work is complete, if the results of that work as well as I think they might, then a longer-term next step might be to consider switching from *.doc to *.fodt [](per https://wiki.documentfoundation.org/Libreoffice_and_subversion) in the repository itself. |
|
So my main interest here is in getting the docs dramatically improved, which requires that users be able to edit the docs in their favorite text editor and do a github pull requests, which means a text format for the documents is kind of required. Otherwise, the workflow everyone is now used to just isn't going to happen. A .fodt file still doesn't make it possible for a user to realistically submit patches, to run grep over the docs to find instances of obsolete urls or what have you, etc. It's not technically a binary file but it isn't that different in practice. You aren't going to merge simultaneous pull requests to different parts of a document that way; the changes can't be done using standard tools, the LibreOffice suite won't keep diffs minimal, and multiple sequential patches won't apply. I've looked extensively at the docs, and they contain no particularly special formatting that can't be captured with markup languages. There's no good reason that any one of a number of popular markup languages couldn't work. I'm willing to be pushed into using a markup language I don't particularly like. However, I don't think the labor of turning things into a LibreOffice document would be a significant improvement to the project. As a side note: I started my hacking career on a PDP-8e in the deep mists of time. I'm an old fogey like the rest of everyone interested in this stuff, and I'd like to see it made much easier to use the simulators the project has to offer and to show them off to younger people. |
|
By the way, if needed, LaTeX could be used here. I don't think it's ideal because you can't turn it into web pages quite so easily, but I have enough experience using tools like HeVeA for the purpose (see https://hevea.inria.fr/ ) that I could probably be badgered into using that instead. Again, my taste would now run elsewhere; there's no complicated formatting in the documents, but any editable text format is probably an improvement over the current situation. |
|
Well troff is the best to do what you want and of course I’m personally
happy with it. It’s still my go to document compiler like many in TUHS (the
Tex family is a mess but that’s a different story). But the core issue here
is neither meets Bob’s base requirement.
This is as far as the argument gets. FWIW: You can grep through flat oft
filed and you can do duffs against them. Look at the url I pointed you at.
But other than something such as the libreOfficecompromise than does
understand what we have and works everywhere, I think Paul’s observation
stands. The SG is not likely to want to change as You will not be able to
solve all the problems and you are going tick people off if you switch to
troff, Tex, scribe or anything that uses a traditional text editor and a
document compiler as each of these systems (like text editors) have
personal followings.
LibreOffuce is far from perfect. I personally don’t use it but I can and
am willing to if we can make it work as well as Doc has so far and can
switch to text XML which .fodt is said to be able too.
Sent from a handheld expect more typos than usual
…On Fri, Nov 1, 2024 at 9:03 PM Perry E. Metzger ***@***.***> wrote:
So my main interest here is in getting the docs dramatically improved,
which requires that users be able to edit the docs in their favorite text
editor and do a github pull requests, which means a text format for the
documents is kind of required. Otherwise, the workflow everyone is now used
to just isn't going to happen.
A .fodt file still doesn't make it possible for a user to realistically
submit patches, to run grep over the docs to find instances of obsolete
urls or what have you, etc. It's not technically a binary file but it isn't
that different in practice. You aren't going to merge simultaneous pull
requests to different parts of a document that way; the changes can't be
done using standard tools, the LibreOffice suite won't keep diffs minimal,
and multiple sequential patches won't apply.
I've looked extensively at the docs, and they contain no particularly
special formatting that can't be captured with markup languages. There's no
good reason that any one of a number of popular markup languages couldn't
work. I'm willing to be pushed into using a markup language I don't
particularly like. However, I don't think the labor of turning things into
a LibreOffice document would be a significant improvement to the project.
As a side note: I started my hacking career on a PDP-8e in the deep mists
of time. I'm an old fogey like the rest of everyone interested in this
stuff, and I'd like to see it made much easier to use the simulators the
project has to offer and to show them off to younger people.
—
Reply to this email directly, view it on GitHub
<#431 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAFRF4AAAKW7HSHLX6TGF6LZ6QQE7AVCNFSM6AAAAABPTNE7ASVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDINJSG43TMMJRGI>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
|
I should have added if it was clear in my original response, no markup
languages or tools for them have been determined to not be sufficient for
the task. As I said this has been looked into. If we can find a
better solution with creating a new set of issues that are as bad or worse
The big issue here is we don’t have tools that are friendly and powerful
enough that meet the need.
Sent from a handheld expect more typos than usual
…On Fri, Nov 1, 2024 at 9:24 PM Clem Cole ***@***.***> wrote:
Well troff is the best to do what you want and of course I’m personally
happy with it. It’s still my go to document compiler like many in TUHS (the
Tex family is a mess but that’s a different story). But the core issue here
is neither meets Bob’s base requirement.
This is as far as the argument gets. FWIW: You can grep through flat oft
filed and you can do duffs against them. Look at the url I pointed you at.
But other than something such as the libreOfficecompromise than does
understand what we have and works everywhere, I think Paul’s observation
stands. The SG is not likely to want to change as You will not be able to
solve all the problems and you are going tick people off if you switch to
troff, Tex, scribe or anything that uses a traditional text editor and a
document compiler as each of these systems (like text editors) have
personal followings.
LibreOffuce is far from perfect. I personally don’t use it but I can and
am willing to if we can make it work as well as Doc has so far and can
switch to text XML which .fodt is said to be able too.
Sent from a handheld expect more typos than usual
On Fri, Nov 1, 2024 at 9:03 PM Perry E. Metzger ***@***.***>
wrote:
> So my main interest here is in getting the docs dramatically improved,
> which requires that users be able to edit the docs in their favorite text
> editor and do a github pull requests, which means a text format for the
> documents is kind of required. Otherwise, the workflow everyone is now used
> to just isn't going to happen.
>
> A .fodt file still doesn't make it possible for a user to realistically
> submit patches, to run grep over the docs to find instances of obsolete
> urls or what have you, etc. It's not technically a binary file but it isn't
> that different in practice. You aren't going to merge simultaneous pull
> requests to different parts of a document that way; the changes can't be
> done using standard tools, the LibreOffice suite won't keep diffs minimal,
> and multiple sequential patches won't apply.
>
> I've looked extensively at the docs, and they contain no particularly
> special formatting that can't be captured with markup languages. There's no
> good reason that any one of a number of popular markup languages couldn't
> work. I'm willing to be pushed into using a markup language I don't
> particularly like. However, I don't think the labor of turning things into
> a LibreOffice document would be a significant improvement to the project.
>
> As a side note: I started my hacking career on a PDP-8e in the deep mists
> of time. I'm an old fogey like the rest of everyone interested in this
> stuff, and I'd like to see it made much easier to use the simulators the
> project has to offer and to show them off to younger people.
>
> —
> Reply to this email directly, view it on GitHub
> <#431 (comment)>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAFRF4AAAKW7HSHLX6TGF6LZ6QQE7AVCNFSM6AAAAABPTNE7ASVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDINJSG43TMMJRGI>
> .
> You are receiving this because you commented.Message ID:
> ***@***.***>
>
|
|
I was just typing a suggestion to use a version of RUNOFF that can run
on some simulated system on any host where simh can run. The formatted
text file it generates can be accessed with any browser. But it comes
back to which RUNOFF on which operating system on which simulated
hardware. :-)
- Aron
…On 11/1/24 21:25, Clement T. Cole wrote:
Well troff is the best to do what you want and of course I’m
personally...]
|
|
p.s. As is my wont, I was thinking of the versions of RUNOFF (or DSR)
for DEC systems, since they may be easier for most users to access than
the versions for CTSS or Multics. :-) I just discovered that man roff
on my Linux box mentions CTSS and Multics as predecessors, but none of
the DEC systems.
FWIW, my most recently preferred documentation tool is Mediawiki *with
the graphviz and mscgen plugins* for embedded source of text-to-graphics
for graphs and message sequence charts.
- Aron
…On 11/1/24 21:32, Aron Insinga wrote:
I was just typing a suggestion to use a version of RUNOFF that can run
on some simulated system on any host where simh can run. The
formatted text file it generates can be accessed with any browser. But
it comes back to which RUNOFF on which operating system on which
simulated hardware. :-)
- Aron
On 11/1/24 21:25, Clement T. Cole wrote:
> Well troff is the best to do what you want [...]
|
Howdy! The documentation is all in .doc files, which makes it hard to track changes in source control, hard to request pulls of fixes to documentation, hard to view the docs online as web pages, etc.
Would the project be willing to accept volunteer labor to convert the docs to markdown or something similar?
The text was updated successfully, but these errors were encountered: