Adding new .docbook for KAddressBook, draft version
ClosedPublic

Authored by davidbryant on Jul 28 2019, 9:06 PM.

Details

Summary

I have written the first two chapters of documentation for KAddressBook, and I'm asking for feedback

BUG: 409998

Test Plan

? I'm new, so I don't know.

Diff Detail

Repository
R204 KAddressBook
Branch
docbook_0.0 (branched from master)
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 14606
Build 14624: arc lint + arc unit
There are a very large number of changes, so older changes are hidden. Show Older Changes
Restricted Application added projects: KDE PIM, Documentation. · View Herald TranscriptJul 28 2019, 9:06 PM
Restricted Application added subscribers: kde-doc-english, kde-pim. · View Herald Transcript
davidbryant requested review of this revision.Jul 28 2019, 9:06 PM
ognarb edited the summary of this revision. (Show Details)Jul 28 2019, 9:15 PM
ognarb added a reviewer: KDE PIM.
ognarb added a subscriber: ognarb.Jul 28 2019, 9:35 PM

Thanks!

Could you move all the images and index.docbook in a subdirectory with the name 'doc'?

lueck added a subscriber: lueck.Jul 29 2019, 4:08 AM

Please use checkXML5 index.docbook to validate XML

index.docbook
31
35
99

<filename class="extension">.csv</filename>
<filename class="extension">.ldif</filename>
<filename class="extension">.vcf</filename>

178

<filename class="extension">.vcf</filename>

422
davidbryant marked 4 inline comments as done.Jul 30 2019, 10:12 AM

Thanks!

Could you move all the images and index.docbook in a subdirectory with the name 'doc'?

Hi, Carl. I got your message, but I'm not sure I understand what you're asking me to do. Please clarify.
Merci beaucoup.

lueck added a comment.Jul 30 2019, 5:30 PM

Hi, Carl. I got your message, but I'm not sure I understand what you're asking me to do. Please clarify.
Merci beaucoup.

docbook and screenshot files should be in a folder called "doc", see e.g https://cgit.kde.org/dolphin.git/tree/

  1. Updating D22799: Adding new .docbook for KAddressBook, draft version #

I made the changes Lueck suggested, plus a few more cosmetic adjustments.
I finally understand that both CCBYSA4 and underCCBYSA4 (XML entities) must be present in index.docbook

lueck added inline comments.Jul 31 2019, 12:59 PM
index.docbook
435

KAddressBook -> Help -> About KAddressBook reads:
"Copyright © 2007–2019 KAddressBook authors", please use it

437–443

Please remove these lines, it is just a placeholder from the template

lueck added inline comments.Jul 31 2019, 1:38 PM
index.docbook
11

please add a line with:

<title>The &kaddressbook; Handbook</title>

  1. Updating D22799: Adding new .docbook for KAddressBook, draft version #

Incorporated changes suggested by Burkhard Lueck
Remember, this is still a rough draft. I was intending to remove Konqui and Tux eventually, in my final draft. I still have many chapters to write. Please be patient.

davidbryant updated this revision to Diff 62970.Aug 2 2019, 1:36 PM
davidbryant marked 3 inline comments as done.
  1. Updating D22799: Adding new .docbook for KAddressBook, draft version #

Revising text a little; also adding a new chapter, with more pictures.
Next chapter will be details about editing contact data, followed by menu reference listing.

yurchor added a subscriber: yurchor.Aug 2 2019, 2:24 PM

Many thanks in advance for fixing these minor typos.

index.docbook
80

Typo: dats -> data

196

Typo: servicetes -> services

607

Typo: maagement -> management

davidbryant marked 4 inline comments as done.Aug 2 2019, 3:50 PM

Thanks for proofreading it, Yuri. I've corrected the typos on my local copy; they'll be fixed the next time I do a diff.

  1. Updating D22799: Adding new .docbook for KAddressBook, draft version #

Wrote another chapter and started coding a Glossary
I need feedback from anyone who is familiar with "Custom Fields" and "Crypto Settings" -- I have never used these features, so I would appreciate some help writing the documentation
for them.

Updating index.docbook once again
New PC, new OS, new screenshots all around. After several false starts, I think it's all patched up correctly

Thanks for your work. Great docs so far. :)

Can you address the previous comments on creating a separate "/doc" folder in KAddressBook code tree and putting the docs (index.docbook and images) there?

It is enough just to move the files in the /doc folder to conform with other KDE applications.

Thanks in advance for your work.

Yeah, Yuri .... Carl Schwan told me about /doc, and I had been doing that. But I recently bought a new PC, and in the process of moving everything off my old machine, I very stupidlly destroyed my cloned copy of the repo. Carl helped me get the index.docbook back with "arc patch", but I didn't have all the old files to put in /doc, so I just started it up as if it were all new stuff (which it mostly was ... I had to redo all the graphic images). Anyway, now I'm on a branch "arcpatch-D22799", and I've created the /doc sub-directory, and I won't erase my copy of the repo ths time. I promise. :) Thanks for your help. I've only got one more chapter to go, I think.

Tweaking images, adding a new chapter, and appendng an appendix.
I think all the images are clean, now. Most of the remaining changes will be to doc-reference.docbook (the appendix).
I've been having horrible problems with Kate, the text editor. Switching to gedit, which is (hopefully) bug-free.

yurchor added inline comments.Aug 31 2019, 5:49 AM
index.docbook
724

I know that we document everything, regardless whether it works, but isn't MSN Messenger discontinued and ceased to work now?

731

Regretfully, LaTeX (our main core to convert DocBook to PDF) does not play well with SVG. Can this and other SVGs be converted to PNGs with a regular convert utility from ImageMagick?

convert file.svg file.png

Tweaking a few images, switching all .svg files to .png format
Small changes only in the verbisge. Converted all Scaleable Vector Graphics to Portable Network Graphics format,
per Yuri's request. Cleaned up five screenshots. Not sure what to do about 23 now superfluous .svg files. Suggestions?

Not sure what to do about 23 now superfluous .svg files. Suggestions?

They are not needed to create the end-user docs. I think that they should not be committed to the repo (my guess is that when the Breeze icon theme is finished, we will have some new "fresh" icon theme ("Every breaking wave on the shore tells the next one there'll be one more", you know)).

  • Basic Document is Now Complete --

Completed Intro through Chapter 5. Glossary and appendices are not yet complete.
I installed openSUSE LEAP 15,1, and now have a stable copy of KAddressBook version 5.10.3.
Documentaton files, including graphics, have been updated to version 5.10.3.

Added more sections to Appendix. Documentation is practically complete. I need help with LDAP.
The new documentation for KAddressBook is practically complete. The only things left are two sections
in the appendix that involve configuring a connection to an LDAP server. I can't find a server to
connect to, so I can't verify that my interpretation of the dialog boxes is correct. If anybody knows
of an LDAP server I may experiment with, please write to davidbryant AT gvtc.com. Or if you know how
those configuration screens work, please explain them to me. Thanks!

first at all thanks a lot for this documentation.

What is the problem with ldap server ?

Final Revision to KAddressBook Documentation.
The new documentation for KAddressBook is now complete. I need help from somebody
who understands KDE's procedures better than I do. I would like somebody to review
this document to be sure it's acceptable. Once any necessary changes have been
made, it should be added to the GIT repository and rolled out for installation in
the various distros. Thanks! (If I need to learn more about using Phabricator to
get some of this stuff done, please let me know.)

Please use

checkXML5 index.docbook

to detect and fix DocBook issues. Some DocBook tags do not play with each other well now.

It is worth to add

if(KF5DocTools_FOUND)
    add_subdirectory(doc)
endif()

into CMakeLists.txt in the root folder (closer to the end of that file, ~ line number 100) and the following CMakeLists.txt in the /doc folder:

########### install files ###############
#
#
kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en SUBDIR kaddressbook)

Thanks in advance for your work.

Revising for checkXML5 editor
Jack Ostroff and Yuri Chornoivan both told me I need to pay more attention to
checkXML5. Document should be clean now. Added a little bit of CMakeList.txt
stuff, per Yuri's instructions. Review / comments / criticism welcome.

I might be wrong, but it looks to me as if the "arc diff" function did not in fact upload the new versions of "docbook-reference.docbook" and "index.docbook" that I had placed in the root directory, and instead uploaded everything from the /doc directory, and nothing from the root. I hope I'm wrong, but it looks as if that is what happened.

Here's a picture from the directory I ran "arc diff" in, just for reference.

david@david-XPS-8930:~/Documents/KDEStuff/kaddressbook$ dir
CMakeLists.txt COPYING.DOC doc index.docbook kaddressbook.renamecategories MAINTAINERS src
COPYING COPYING.LIB docbook-reference.docbook kaddressbook.categories kontactplugin Messages.sh

Have you committed the changes locally (git commit --amend)? As far as I know, arc diff simply tries to find the last commit and push it, updating the existing one if it is already there.

"Have you committed the changes locally (git commit --amend)? As far as I know, arc diff simply tries to find the last commit and push it, updating the existing one if it is already there."

I'm just following the directions Carl Schwan gave me. My understanding is that I put the new files in the root directory, then say "arc diff", then move the new files to the /doc subdirectory. Rinse, and repeat. That's what I've been doing all along, and most of the time it seemed to work correctly. If that's wrong, please let me know. I'm just a babe in the woods when it comes to "git" and "arc" and all that. I understand MVC and BXLE (old IBM mainframe machine instructions) very well. This new stuff, not so much.

Maybe somebody could try running "checkXML5" on index.docbook. If that comes up clean, the newest version was uploaded. If not, I guess I need to try again.

The diff was updated but not all XML errors were fixed.

Can you use "arc diff" once more with the files attached?

Thanks in advance for your work.


Trying once again to get all my changes uploaded.
The version I thought was the current index.docbook is now in /doc subdirectory.
I'm also pushing some totally inconsequential changes (extra white space inside
a <!-- xxx --> comment) in hopes I'll finally get the final version to
upload correctly.

It looks like it's good this time. Finally! Thanks for the help, y'all.

yurchor accepted this revision as: yurchor.Sep 18 2019, 4:53 AM

Thanks.

The images can be compressed from ~3 MB to ~1 MB with a simple script

#!/bin/sh

for i in *.png
do
     pngnq -s 1 "$i" && advpng -z4 "${i%.*}-nq8.png" && mv -f "${i%.*}-nq8.png" "$i"
done

But otherwise, it looks good.

This revision is now accepted and ready to land.Sep 18 2019, 4:53 AM

So I'm curious ... are there additional steps needed? It's been 11 days since Yuri said "ready to land". It looks as if this stuff needs to be moved into the GIT repository. Who's supposed to do that? When?

In general, the procedures here seem somewhat arcane and mysterious to a newcomer like me. Is there somewhere -- maybe in one of the wikis -- where some of the procedures are spelled out.?I'm willing to help out with fixing the documentation, but I'd also like to have a better understanding of the big picture.

Thanks!

So I'm curious ... are there additional steps needed? It's been 11 days since Yuri said "ready to land". It looks as if this stuff needs to be moved into the GIT repository. Who's supposed to do that? When?

In general, the procedures here seem somewhat arcane and mysterious to a newcomer like me. Is there somewhere -- maybe in one of the wikis -- where some of the procedures are spelled out.?I'm willing to help out with fixing the documentation, but I'd also like to have a better understanding of the big picture.

Thanks!

Can you compress the images with the script from @yurchor? I suppose you don't have commit access, so for this commit so me or @yurchor will need to push for you.

In the future, if you want to continue contributing to KDE, you can can request commit access to all the repositories: https://community.kde.org/Infrastructure/Get_a_Developer_Account.

Uploading Compressed Images
Sorry, Yuri. I misunderstood your comment, and did not realize you wanted
me to compress the files. I didn't use that script ... I used a program
called "pngquant". But the result is about the same. Images reduced from
about 3.1 MB to 1.1MB (65%). Carl, Ill apply for that developer account,
but I'll definitely need assistance with "pushing" a commit.

I guess I'll have to do it again. I put the new images in the root directory, but "arc diff" actually uploaded the old copies of the images. Something about this process is very confusing, to me.

Doing it gain. It seems to be uploading the "/doc" subdirectory, and
not the contents for the root cloned directory. This arc utility is
very confusing. Guess I just have to check the result every time.

Well, I tried to fix it. But it appears something is broken. I double-checked. The file named "kaddressbook94.png" was 25.3 KB in both my root cloned directory and in my "/doc" sub-directory when I ran this last upload. But the audit trail above shows 75 KB. Any suggestions? From what I can see, "arc" says it's uploadng new files, but doesn't actually do the job.

From my terminal window (part of "arc diff" output):

A (img) doc/addressbook91.png
A (img) doc/addressbook92.png
A (img) doc/addressbook93.png
A (img) doc/addressbook94.png
A (img) doc/addressbook95.png
A (img) doc/application-exit.png

Well, I come back an hour later, and now it appears that the compressed files have been uploaded. Apparently there's some sort of time lag involved, because I've done nothing in the interim, but now the "diff" lines show the compressed file sizes..

Thanks for all your work.

This revision was automatically updated to reflect the committed changes.