unfoldingword/book-package-app

Book Package App

Book Package App

This project is described in some detail in DesignSpec.md.

The main requirement is documented in Issue #2. In addition, from Issue #3, there is a feature called Book Package Flow Optimization. This allows the user to indicate which parts of a book package are completed. This indicates that the UI needs to permit two essential functions:

• specifying the books to be included in the package, and
• of those specified, which are completed.

NOTE: the books marked completed may not actually be completed. This will be true when doing 'what if' studies. Thus there is no verification to be done on books marked as completed.

Original README

The below was created by the yarn create command

This project was bootstrapped with Create React App.

Available Scripts

In the project directory, you can run:

yarn start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

yarn build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

yarn eject

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Learn More

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

book-package-app's Issues

Support permalinks with URL params

It would be nice to be able to share a link to a "recipe" by using URL parameters to specify what books are being used. For an example, you can see the translation helps prototype:

https://unfoldingword-box3.github.io/translation-helps/?owner=door43-catalog&rc=/en/ult/gen/1

In our case we might want compatibility with tC Create patterns listed in unfoldingWord/tc-create-app#28 ?

It may depend on whether gitea react toolkit supports any of this?

Anyway, we'd at least need to be able to support the DCS owner to look at (unfoldingWord right now), and then also a list of books to review. It could be as simple as

• owner
• books

Looking like this: /?owner=unfoldingword&books=gen,exo

You'd want to app to update the URL when the user navigates, too.

Add Select All for NT/OT

At the top of each of the OT and NT list of books on the first screen, it would be nice to have a "Select All" button. Possibly it would be clearer if the one button said "Select OT" and the other one said "Select NT".

Count Inflation

Some books have high numbers of names and places which are covered by translation word articles. This makes the word counts higher than expected. Would it be of value to allow an option to ignore this source of word counts?

This source is https://git.door43.org/unfoldingWord/en_tw/src/branch/master/bible/names.

@jag3773

Book Package Details

Use the following as a template for modify Step 2 in the app. First, let's title it "Book Package Details" in the stepper.

Instructions

The instructions on the page are actually the instructions for step 3, Optimize. I wonder if we can move all of it to Step 3? See other issue for notes on this. So this section would just have the Back | Next buttons on it.

BP Information

Re-flow the BP information using the following as an example, using 1 and 2 John. I'm thinking of something like Tree View https://material-ui.com/components/tree-view/. Note the order of the resources below too.

---

> Book Packages Total Word Count: 72,932

When expanded, it would reveal these indented:

> 1 John Book Package Word Count: 61,135

> 2 John Book Package Word Count: 20,668

When those are expanded, they would reveal each component (indented), which would also be a dropdown. I've expanded them in the example below so I don't have to repeat them twice.

⌄ ULT Word Count: 319

[Word Frequency Table]

⌄ UST Word Count: 498

[Word Frequency Table]

⌄ Translation Academy Word Count: 7,373

Linked modules: 7 unique, 14 total links
[Table of links]

⌄ Translation Words Word Count: 11,254

Linked articles: 37 unique, 69 total links
[Table of links]

⌄ Translation Notes Word Count: 936

Number of Notes: 33
[Word Frequency Table]

⌄ Translation Questions Word Count: 11,254

Number of Questions: 11
[Word Frequency Table]

Links to UTA are broken

Clicking a UTA link yields https://git.door43.org/unfoldingWord/en_ta/src/branch/master/translate/[object%20Object]. Of course the object object part should the folder and filename...

Add spreadsheet export

In step two, there should be a button to download a csv file of the word count data. The csv file should have the following columns:

book,ult,ust,utn,utq,utw,uta

An example row would be:

3jn,312,527,1029,320,10206,10509

Note that ALL books of the Bible should always be included, in canonical order. Books not selected should show blank values.

Name the button "Export".

Exports - two problems

The two items below were reported:

• The BPA export button in the Book Package Details step only seems to download the counts for the 5 terms that are displayed at any given time.

• the Details section seems to include the word list for all resources. The only way to get the word list for just the UST, for example, would be to do an export for each individual book, but that would only work after more than the five displayed words are exported.

Book Package Flow Optimization

In addition to the basic reporting of what's in a BP (#2), it would be very helpful if the app could calculate the ideal next best books based on total word count of the BP.

This should accept an optional list of already completed book packages, in which case the app would identify all the parts which would have already been translated and suggest the next set of books that could be translated with the least amount of new content.

Setup on Custom Domain

We should probably go the next step here and set this to run on one of our domains for easier accessibility.

Design Tweaks

Here's a list of several design tweaks, let me know if you need more info for any of these... some are negotiable if need be :)

Overall

• Use the uW logo for the favicon
• Set a margin on the whole screen so that stuff doesn't bump the edges... maybe something like margin: 3%.
• Center the divs below the stepper. May need to specify something like max width of 600px or something?
• Center the navigation (Back, Next, Reset) and everything above it
• Add a header bar with a menu and put the "Refresh Book Package Data" toggle in that menu.
• Do not use the book short codes anywhere... e.g. always say "1 John" not "1jn"
• Let's try to only say total when we are providing a roll up total... so we might only see "total word count" once on a page.
• Use commas for the thousands separator, e.g. (60,000)

For the above, see the overall layout of https://create.translationcore.com. Gray background like that app has helps with visual contrast too.

Step 1

• List the books of the Bible in two columns, start column 2 with NT

Step 2

• During calculation stage, show a loading type of spinner until all the data is available, then reveal.

See more notes in #8

Step 3

• Instructions for this step should appear on this page
• Remove "Select any books completed, then click Next to optimize book package flow"
• The instructions label for the check boxes should say "Check completed book packages or none"
• There should be an "Optimize Flow" button to start the calculation
• On button press there should be a loading type of spinner just like in step 2
• Display the resulting output like this (not unordered list for completed BPs and ordered list for flow suggestion):

Book Package Flow Optimization

If these Book Packages are completed:

• Titus (Book Package Word Count: 59,929)
• 1 John (Book Package Word Count: 61,135)

Proceed in this order:

1. 2 John–Adjusted Book Package Word Count: 3,554
2. 3 John–Adjusted Book Package Word Count: 4,132

Possible misinterpretation of "unique" word counts

The unique word count is subject to misinterpretation, namely, is it an indicator of effort or is it a measure of complexity of vocabulary. It isn't the first, but the second.

Question: given this possible misapplication, should we avoid showing it?

@jag3773

Book Selection UI

The main part of this app will be selecting a book or several books and getting statistics for them.

This could be implemented as a stepper, or a transfer list, or a set of check boxes with a button.

Add resource based totals

At the top of step two we have the book packages total. It would also be helpful to list down the resource totals (UTN word count for all BPs selected) for all of the book packages selected.

Electron copy link problem

When running as standalone as Electron app, the copy link yields something like this:
file:///C:/Users/mando/AppData/Local/Programs/book-package-app/resources/app.asar/app/index.html?books=1jn,2jn,3jn

The link should be something like:
https://unfoldingword.github.io/book-package-app/?books=1jn,2jn,3jn

So the fix is to examine the base for a link that begins with file:// and use the online base instead.

Summary Export does not handle OBS correctly

Looks like the table needs some adjusting because of OBS:

The OBS column should only have a value in the OBS row
The OBS row should NOT have values for ULT and UST. Looks the values are just taken from the previous row.

ref:here

Add OBS resources to the Book Package App

Need the OBS resources in the new tsv file format (https://git.door43.org/unfoldingWord/en_translation-annotations/src/branch/master/obs/obs_twl.tsv) to be added to the OBS app.

Provide version and source for UTA and UTW articles

From Russ Perry here:
https://unfoldingword.zulipchat.com/#narrow/stream/209457-SOFTWARE/topic/Book.20Package.20App/near/194431344

This morning, I demoed the Book Package App for BCS. It is timely for them to have it since they were having to open tC and look through it to find what tW and tA articles are referenced for a book package. They feel it will be helpful for them. One request they had is to add the version info and repo source where the UTA and UTW article info and counts are coming from. That's specifically for the BookPackageDetails CSV file, but may be useful elsewhere, too. Is that doable?

I asked two follow-up questions:

1. What would you say is the version of this tW article?
   https://git.door43.org/unfoldingWord/en_tw/commits/branch/master/bible/kt/abomination.md
2. And would say the repo/source is the link above?

Optimized Flow subtotals

See here

Add Chart in Optimize Output

In addition to the tweaks in #9, it would be great if we could add a chart that gives a visual representation of word count.

Maybe a chart that shows word count on y axis and books on the x axis, but connect points together to create a line chart:

Of course it should mostly be a downward trend, but not entirely.

Maybe use something like https://github.com/jwilber/roughViz if you're feeling more relaxed, or see some other libraries in https://reactjsexample.com/tag/chart/.

Optimize results are not blanked out when moving back and forth

This is a problem when do a more than a few books. It takes a while to re-compute and re-display the new results.

Add drop down of unique articles on BPF optimize step

Content team would like to see a drop down that shows the unique UTA and UTW articles that show up in each book that has been optimized.

For instance, a click and drop down report under each of these:

That would make it easy for them to see which articles are unique in those books given what they have already translated.

Export does not include OBS or its resources

Change "Reset" to "Start Over"

On the final screen there is a "Reset" button which takes one all the way back to the beginning, I think that "Start Over" would indicate a complete reset better.

UTQ Error: Request failed with status code 404

The app is throwing this error on step two of the process. I guess the "en_tq" repo had a different file structure when the files were in .md, and now they are in .tsv it can't find the right files.

UTQ Error on:https://git.door43.org/api/v1/repos/unfoldingword/en_tq/contents/tit/01 is:Error: Request failed with status code 404

Obtain tW articles from the new TWL TSV files

Optimized flow details and export

Currently the optimized display only shows the optimized order/flow of work, but not the details (which are on other steps). The request is to:

First, add counts to the UTA and UTW on the UI. Today, it shows this:

Unique UTA modules
- figs-explicit  (References: 6)
- figs-hendiadys  (References: )
- figs-idiom  (References: 3)
- figs-metaphor  (References: 50)
- figs-metonymy  (References: 28)
- figs-you  (References: 2)
- guidelines-sonofgodprinciples  (References: 12)

It shows number of times referenced, but not the number of words in the document, which is being requested.

Second, a new export is requested to capture in a spreadsheet the optimized flow data in detailed form.

The thread below indicates that of the two, the export with details is more important.

See Zulip thread:
https://unfoldingword.zulipchat.com/#narrow/stream/209457-SOFTWARE/topic/Book.20Package.20App/near/214986299

@birchamp @jag3773

Reset button does not clear checkboxes

Support Specifying book code in URL

We need persistent URLs to any book selection allowed in the app's UI.

e.g. something like, /bp=rut and /bp=rut,jon,tit and /bp=nt, etc.

Integrate and Report Content Validation

Of interest to:
@BincyJ
@birchamp
@PhotoNomad0
@RobH123

Per brief discussion, the current thinking is to include a new table of results after/before the work count frequency table that shows results of the Content Validation RCL.

Add confirmation to Delete Local Cache

Since this completely removes all cached data, a confirmation that the user really wants to do that would be a good idea.

REF: https://unfoldingword.zulipchat.com/#narrow/stream/209457-SOFTWARE/topic/Book.20Package.20App/near/236531036

The uW favicon isn't showing on deployed version of app

It does show correctly when running local...

https://unfoldingword.github.io/book-package-app/

Permalinks to entire NT or OT

Allow nt and ot as valid parameters for books ? That way the selection of all the OT or all the NT is more easily referenced?