search

openlcb / documents

The OpenLCB specification: standards, recommended practices and other documentation.
3 stars 7 forks source link

Adopt CAN Physical Layer S&TN #145

Closed bobjacobsen closed 4 months ago

balazsracz commented 4 months ago

It appears that the change markers for these documents are not correct. The baseline of change markings seem to be not the previous standard.

This is most visible in the DCC section (section 6 in S). This is an entirely new section. However, in the change marked PDF it looks like this:

image

which suggests that the baseline ODT already had some text in section 6 before.

I don't really know how to fix this.

bobjacobsen commented 4 months ago

When I go back to commit d6f1c9df, which has the changes still in the .odt file, the internal change log for CanPhysicalS.odt shows:

It looks like change-tracking wasn't enabled when the first edits of Section 6, including 6.1, were made.

If we really have to, we can use the full set of changes recorded by the /generated/CanPhysical*.txt files in PR #46 to figure out what changed there, then manually mark those sections of the document as changed. That's tricky, but it could be done. It won't match the git history to the changes in the .odf file though.

Is that step really necessary?

1) The relevant sections have change bars down their complete left side, so it's clear that these sections have been modified. It's not clear that they're entirely new, though. 2) We've never even published the files with changes marked before. This is something new.

balazsracz commented 4 months ago

Word has a feature where it can "compare documents", meaning that you give it two versions of the same file (in two .doc files that is), and it will turn the diff into something like the change markers we have.

Does openoffice have that? If yes, we could use that feature to diff the previous standard version with the new standard version (take both versions after all changes were accepted). This way we won't rely on the change tracking feature to be correctly used.

I am not supportive of redoing all edits from scratch. It's both a bad use of our time and not guaranteed to yield results that are correct.

However, if we can't find a way to make the -changes-.pdf to show the actual diff, then we should rather not publish it at all. Having bad information is worse than not having information.

bobjacobsen commented 4 months ago

I'm experimenting with the LibreOffice "compare changes" tool. It seems to be doing some non-intuitive things. More to follow.

bobjacobsen commented 4 months ago

I've been able to make PDF files with changes for both the S&TN. Some observations:

Should I add these PDFs to this PR in standards/changes/ ?

balazsracz commented 4 months ago

Yes please add these to the pr and overwrite the incorrect changes files with them.

-- Sent from my mobile device

On Tue, Jul 16, 2024, 16:15 Bob Jacobsen @.***> wrote:

I've been able to make PDF files with changes for both the S&TN. Some observations:

  • They seem to match the text changes in the .txt files properly.
  • There are a couple places where it seems to be confused about formatting in the changes, e.g. marking some old text as bold near line 25 in the Standard, but I don't think that's a significant problem.
  • There are also marked changes that don't seem to be real changes e.g. in the table in section 4 of the Standard
  • These are visually much cleaner, with only one color marking the changes and no overlapping change marks.

Should I add these PDFs to this PR in standards/changes/ ?

— Reply to this email directly, view it on GitHub https://github.com/openlcb/documents/pull/145#issuecomment-2231013809, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA4MECQLQGQTD4OZDIHTBQLZMUTGZAVCNFSM6AAAAABKZBHNS6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMZRGAYTGOBQHE . You are receiving this because you commented.Message ID: @.***>

bobjacobsen commented 4 months ago

Yes please add these to the pr and overwrite the incorrect changes files with them.

Done!

balazsracz commented 4 months ago

This is very good, thank you!