docs_devel: update contribution manual about document build and others #908

miurahr · 2024-01-14T07:01:46Z

Pull request type

Documentation -> [documentation]

Which ticket is resolved?

What does this PR change?

Fix URL typo
Add section about manual build tasks and explanation of container
Update about documentation project rules and procedures

Other information

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

Remove duplication with the contribution guide, and replace with links to the guide Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr · 2024-01-16T23:53:53Z

There are almost a technology side of document build, not about contribution rules and procedures.

A missing part is a build property option to skip html manual build when building and testing features.

Kazephil · 2024-01-18T08:36:05Z

@miurahr
like the idea of splitting the developer documentation into a contribution guide and a build manual.

There's a lot of material in the developer documentation, so I'm going to wait until I can set aside a good chunk of time to do a proper review, which probably means sometime early in April, when work gets quieter.

Until then, I think we can still push the updates as is (maybe with a DRAFT label) to make information available. (It'll also be easier to review if it's up on the readthedoc.io site you set up.)

@brandelune What do you think?

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr · 2024-01-18T13:47:16Z

There is very small section about a document contribution rule and procedure

https://github.com/omegat-org/omegat/blob/d875fb7795f7c1233d63d4afd3f18a3a55912718/docs_devel/docs/40.ContributingDocument.md

miurahr · 2024-01-18T13:48:17Z

docs_devel/docs/40.ContributingDocument.md

+Please contact to [Documentation manager](https://omegat.org/about) at [omegat-development mailing list]
+(https://sourceforge.net/projects/omegat/lists/omegat-development) for details.


There is a space character between link text and url

Suggested change

Please contact to [Documentation manager](https://omegat.org/about) at [omegat-development mailing list]

(https://sourceforge.net/projects/omegat/lists/omegat-development) for details.

Please contact to [Documentation manager](https://omegat.org/about) at [omegat-development mailing list](https://sourceforge.net/projects/omegat/lists/omegat-development) for details.

Why would people need to contact the documentation manager ? People can do as they do for the code. Send PRs after creating issues on SF, on the documentation tracker.

Because I cannot find any document to describe rules and procedure in omegat.org website, and also in source tree. Please give a description. Otherwise, I can revert it to previous sentence; "[TBD]".

This may be valuable to add from https://omegat.org/support

documentation issues are handled on SourceForge by the Documentation tracking system. Please do not use these tracking systems before first raising the issue on the user group and/or mailing lists.

docs_devel/docs/45.LocalizeApplicationAndManuals.md

A few rewording suggestions.

Various changes. I put comments preceded by "->".

Few more fixes.

I removed most of the promotion for Docker and restructured the document a bit. I think most of the last part is irrelevant now that we use containers. I've added comments prefixed with "->".

Added reference to contribution rules, etc.

Add the link to Kos' explanations.

Small modifications

Various small fixes and a comment (check "->")

brandelune · 2024-01-19T09:12:56Z

@miurahr @Kazephil I have amended all the documents directly on the branch. There are a few comments (check lines that start with "->").

Thank you very much Hiroshi for this tremendously important work.

Fix typo and slight rewording.

Kazephil · 2024-01-20T01:53:32Z

docs_devel/docs/07.ManualContainerTaskBuild.md

 # Fonts
+
+-> Aren't the fonts installed in the container?


They should be. This would apply to building the documentation without using a container, which requires the user to manually install all font and software dependencies.

Sure, and if we still have the possibility to make manual build, I don't understand why we have a container requirement.

It should probably be called a container option.

In theory, a container makes building the documentation easier than the manual process because it… well… contains everything!

Something strange seems to be going on with the manual build process, though. I'm getting everything inside a literal ${target} directory in doc_src\en\ instead of in the correct docs\en\ folder if I try to build with Ant. More investigation required.

Something strange seems to be going on with the manual build process, though. I'm getting everything inside a literal ${target} directory in doc_src\en\ instead of in the correct docs\en\ folder if I try to build with Ant. More investigation required.

OK. It looks like building the documentation manually now requires passing both the -Dtarget and the -Dlanguage arguments to Ant.

I'm not sure why it didn't need to be passed explicitly before but is necessary now.

I think it might be a good idea to split this file into separate "using a container to build the documentation" and "building the documentation manually" files.

I think it might be a good idea to split this file into separate "using a container to build the documentation" and "building the documentation manually" files.

I agree. Thank you.

I will work it.

docs_devel/docs/07.ManualContainerTaskBuild.md

Kazephil · 2024-01-20T01:59:29Z

docs_devel/docs/40.ContributingDocument.md


 ### License

-All the files in `doc_src` folder and below are under the terms of the GNU General
+All the files in `doc_src` folder and below are published under the terms of the GNU General


@brandelune
I'm not a licence expert, but do software licenses apply to documentation?
Should this be one of the Creative Commons licenses?

The GPL is not specifically a software licence. It is a source code distribution licence. Our docbook sources are not supposed to have issues that can only be solved by using documentation specific licences. But if you find such issues, we need to investigate how to fix them, because changing the licence would be a major pain.

If XML is considered code, then there's probably no problem because the docbook sources can be defined as "source code".

I'll trust that whoever first chose the licence checked this at the time! :)

Originally, the manual was in HTML. There was no build process involved. The whole set was distributed under the GPL, and it just stayed like that. The Emacs manuals use the GFDL 1.3+ which makes sense, if I remember well, because they can also be distributed as books (cf. invariant clauses, etc.)

Interesting.

I found this interesting thread that's relevant.

If I understand it correctly, GPL for the docbook sources is fine. The actual manual(s) produced from those sources should probably be under the GFDL or one of the Creative Commons licences.

If I understood the thread (and GNU GPL FAQ) correctly, licensing the actual manual (output HTML, PDF, etc.) under the GPL would require including the contents of doc_src with the manual itself, which I think would be (a) cumbersome for us, and (b) tedious for users.

Of course, I might simply be misunderstanding the answers in the thread and FAQ.

FSF recommend GFDL for document rather than GPL in several reason.
https://www.gnu.org/licenses/license-recommendations.html

It is something extra-ordinal to apply GPL to a large manual document like OmegaT manual, so I try to add explanation here.

I understand that our choice of licence may not be the best, but we currently do not have issues that need to be solved by a change of licence.

It could be a fun exercise to track down the various authors that share the copyright on the current document though.

Well, the statement in the developer documentation here only applies to the docbook sources, so as far as those go, I think the developer documentation is fine as is in terms of contents.

The broader licensing issue may (or may not) be something to look at further down the road in the larger context of the entire project.
Have we explicitly applied the GPL (or any other licence) to the products output from those sources?

The GPL applies to the deliverables (the "program") and forces the developers to provide sources on demand so that users can modify the deliverable. The GPL is not a source file distribution licence.

Wording change, because documentation isn't really "developed". :)

Wording tweaks.

docs_devel/docs/93.BuildingInstallerPackage.md

Various wording tweaks.

brandelune · 2024-01-20T09:39:27Z

licensing the actual manual (output HTML, PDF, etc.) under the GPL would require including the contents of doc_src with the manual itself, which I think would be (a) cumbersome for us, and (b) tedious for users.

The requirement is only and minimally access to the code upon request. Which we do by default since the code is always available. Just like we do not distribute the OmegaT code with the binaries but keep it available online.

Rewording of section on building Linux native packages using `jpackage`

docs_devel/docs/93.BuildingInstallerPackage.md

Co-authored-by: Hiroshi Miura <miurahr@linux.com>

docs_devel/docs/02.HowToBuild.md

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr · 2024-02-10T04:38:42Z

Now all the reviewer feedback to be fixed are resolved.

omegat-org#908) * docs_devel: update document contribution manual Signed-off-by: Hiroshi Miura <miurahr@linux.com> * docs_devel: Fix link URLs Signed-off-by: Hiroshi Miura <miurahr@linux.com> * docs_devel: Split manual contribution guide and build manual Signed-off-by: Hiroshi Miura <miurahr@linux.com> * docs: update doc_src/Readme.md Remove duplication with the contribution guide, and replace with links to the guide Signed-off-by: Hiroshi Miura <miurahr@linux.com> * docs_devel: explain about build task and how to skip manual generation Signed-off-by: Hiroshi Miura <miurahr@linux.com> * Update Readme.md A few rewording suggestions. * Update 02.HowToBuild.md Various changes. I put comments preceded by "->". * Update 02.HowToBuild.md Few more fixes. * Update 07.ManualContainerTaskBuild.md I removed most of the promotion for Docker and restructured the document a bit. I think most of the last part is irrelevant now that we use containers. I've added comments prefixed with "->". * Update 40.ContributingDocument.md Added reference to contribution rules, etc. * Update 45.LocalizeApplicationAndManuals.md Add the link to Kos' explanations. * Update 92.CodeSigning.md Small modifications * Update 93.BuildingInstallerPackage.md Various small fixes and a comment (check "->") * chore: Update 02.HowToBuild.md * chore: Update 02.HowToBuild.md Fix typo and slight rewording. * chore: Update 40.ContributingDocument.md Wording change, because documentation isn't really "developed". :) * chore: Update 45.LocalizeApplicationAndManuals.md Wording tweaks. * chore: Update 92.CodeSigning.md * chore: Update 93.BuildingInstallerPackage.md Various wording tweaks. * chore: Update 93.BuildingInstallerPackage.md Rewording of section on building Linux native packages using `jpackage` * chore: Apply suggestions from code review Co-authored-by: Hiroshi Miura <miurahr@linux.com> * chore: Delete resolved inline comment in 93.BuildingInstallerPackage.md * docs_devel: split document build manual Signed-off-by: Hiroshi Miura <miurahr@linux.com> --------- Signed-off-by: Hiroshi Miura <miurahr@linux.com> Co-authored-by: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org> Co-authored-by: kazephil <kazephil@gmail.com>

docs_devel: update document contribution manual

f5f24a8

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr added the documentation label Jan 14, 2024

miurahr requested a review from Kazephil January 14, 2024 07:02

miurahr added 2 commits January 15, 2024 06:51

docs_devel: Fix link URLs

5602967

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

docs_devel: Split manual contribution guide and build manual

2cb489d

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr requested a review from brandelune January 14, 2024 22:03

docs: update doc_src/Readme.md

9b9101f

Remove duplication with the contribution guide, and replace with links to the guide Signed-off-by: Hiroshi Miura <miurahr@linux.com>

docs_devel: explain about build task and how to skip manual generation

d875fb7

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr changed the title ~~docs_devel: update document contribution manual~~ docs_devel: update contribution manual about document build and others Jan 18, 2024

miurahr commented Jan 18, 2024

View reviewed changes

docs_devel/docs/45.LocalizeApplicationAndManuals.md Outdated Show resolved Hide resolved

docs_devel/docs/45.LocalizeApplicationAndManuals.md Outdated Show resolved Hide resolved

Jean-Christophe Helary added 8 commits January 19, 2024 10:42

Update Readme.md

eab8d7c

A few rewording suggestions.

Update 02.HowToBuild.md

75ed66c

Various changes. I put comments preceded by "->".

Update 02.HowToBuild.md

b4554c2

Few more fixes.

Update 07.ManualContainerTaskBuild.md

307cb9d

I removed most of the promotion for Docker and restructured the document a bit. I think most of the last part is irrelevant now that we use containers. I've added comments prefixed with "->".

Update 40.ContributingDocument.md

0d51fd1

Added reference to contribution rules, etc.

Update 45.LocalizeApplicationAndManuals.md

1e5d9b4

Add the link to Kos' explanations.

Update 92.CodeSigning.md

62f41c2

Small modifications

Update 93.BuildingInstallerPackage.md

420b3dd

Various small fixes and a comment (check "->")

Kazephil added 2 commits January 20, 2024 10:41

chore: Update 02.HowToBuild.md

9e6e868

chore: Update 02.HowToBuild.md

8f6ec9f

Fix typo and slight rewording.

Kazephil reviewed Jan 20, 2024

View reviewed changes

docs_devel/docs/07.ManualContainerTaskBuild.md Outdated Show resolved Hide resolved

Kazephil reviewed Jan 20, 2024

View reviewed changes

Kazephil added 2 commits January 20, 2024 11:03

chore: Update 40.ContributingDocument.md

665e714

Wording change, because documentation isn't really "developed". :)

chore: Update 45.LocalizeApplicationAndManuals.md

422d336

Wording tweaks.

chore: Update 92.CodeSigning.md

884541e

Kazephil reviewed Jan 20, 2024

View reviewed changes

docs_devel/docs/93.BuildingInstallerPackage.md Outdated Show resolved Hide resolved

chore: Update 93.BuildingInstallerPackage.md

d3dcb62

Various wording tweaks.

chore: Update 93.BuildingInstallerPackage.md

60e4559

Rewording of section on building Linux native packages using `jpackage`

Kazephil reviewed Jan 21, 2024

View reviewed changes

docs_devel/docs/93.BuildingInstallerPackage.md Outdated Show resolved Hide resolved

miurahr commented Jan 22, 2024

View reviewed changes

docs_devel/docs/93.BuildingInstallerPackage.md Outdated Show resolved Hide resolved

miurahr commented Jan 22, 2024

View reviewed changes

docs_devel/docs/93.BuildingInstallerPackage.md Outdated Show resolved Hide resolved

Kazephil and others added 2 commits January 22, 2024 17:13

chore: Apply suggestions from code review

e20bdde

Co-authored-by: Hiroshi Miura <miurahr@linux.com>

chore: Delete resolved inline comment in 93.BuildingInstallerPackage.md

dc01f69

miurahr commented Jan 24, 2024

View reviewed changes

docs_devel/docs/02.HowToBuild.md Outdated Show resolved Hide resolved

docs_devel: split document build manual

ba4c967

Signed-off-by: Hiroshi Miura <miurahr@linux.com>

miurahr merged commit 64be720 into master Feb 10, 2024
9 checks passed

miurahr deleted the topic/miurahr/docs_devel/documentation/how-to-build-manuals branch February 10, 2024 04:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs_devel: update contribution manual about document build and others #908

docs_devel: update contribution manual about document build and others #908

miurahr commented Jan 14, 2024 •

edited

Loading

miurahr commented Jan 16, 2024

Kazephil commented Jan 18, 2024

miurahr commented Jan 18, 2024

miurahr Jan 18, 2024 •

edited

Loading

brandelune Jan 18, 2024

miurahr Jan 18, 2024

miurahr Jan 18, 2024

brandelune commented Jan 19, 2024

Kazephil Jan 20, 2024

brandelune Jan 20, 2024

Kazephil Jan 20, 2024

Kazephil Jan 23, 2024

brandelune Jan 23, 2024

miurahr Jan 25, 2024

Kazephil Jan 20, 2024

brandelune Jan 20, 2024

Kazephil Jan 20, 2024

brandelune Jan 20, 2024

Kazephil Jan 20, 2024

Kazephil Jan 20, 2024

miurahr Jan 20, 2024

brandelune Jan 20, 2024

Kazephil Jan 20, 2024

brandelune Jan 20, 2024

brandelune commented Jan 20, 2024 via email

miurahr commented Feb 10, 2024

		Please contact to [Documentation manager](https://omegat.org/about) at [omegat-development mailing list]
		(https://sourceforge.net/projects/omegat/lists/omegat-development) for details.

docs_devel: update contribution manual about document build and others #908

docs_devel: update contribution manual about document build and others #908

Conversation

miurahr commented Jan 14, 2024 • edited Loading

Pull request type

Which ticket is resolved?

What does this PR change?

Other information

miurahr commented Jan 16, 2024

Kazephil commented Jan 18, 2024

miurahr commented Jan 18, 2024

miurahr Jan 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandelune commented Jan 19, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandelune commented Jan 20, 2024 via email

miurahr commented Feb 10, 2024

miurahr commented Jan 14, 2024 •

edited

Loading

miurahr Jan 18, 2024 •

edited

Loading