El Dilluns, 27 de febrer de 2012, a les 22:57:26, Burkhard L?ck va escriure: > Am Sonntag, 26. Februar 2012, 23:23:23 schrieb Albert Astals Cid: > > Sorry for the top posting :-) > > > > One question about "Building blocks", i think you told me the idea was > > that > > "Building blocks" would be a separate manual, meaning that the Okular > > manual (using Okular as example here) would no longer have the information > > of how the "File" menu works, but instead if would have a link to the > > "Building blocks" manual that speaks of the "File" menu. > > > > Is this right or did I misunderstood you? > > Somehow you misunderstood me resp. the use case for the "Building blocks". > > Using the okular docs as example, there are some "File" menu items special > to Okular. > Of course these items (Import PostScript as PDF, Save As, Save Copy As, > Print Preview, Properties, Embedded Files, Export As etc.) will be in the > Okular docs. > And if there are other items in the Okular "File" menu with more infos as in > the current "Building blocks" documentation ("File ? Open" for example) and > if these infos are valid for other applications as well, these docs will be > used to extend/update the building blocks documantation. > > A better example where the building blocks documentation will simply replace > application docs is the Help menu or Settings ? Configure Shortcuts or > Settings ? Configure Toolbars. > This documentation is shared and valid for nearly all other > KDE-Applications, so it makes no sense to have it in a lot of docbooks.
I disagree, it makes sense from the point of view of being complete, i.e. I want the user to be able to understand all Okular menus just reading the Okular documentation. Will that be possible using "Building Blocks"? Or will he need to open a second documentation? Albert > > > El Diumenge, 5 de febrer de 2012, a les 23:03:58, Burkhard L?ck va escriure: > > > Am Sonntag, 5. Februar 2012, 00:47:57 schrieb Albert Astals Cid: > > > > Could you give a quick summary of what building blocks is for the > > > > people that haven't been following the discussion much? > > > > > > The actual version of building blocks can be found in > > > http://websvn.kde.org/branches/work/doc/buildingblocks/ > > > > > > Credits for the name and idea go to Chusslove > > > (http://lists.kde.org/?l=kde- i18n-doc&m=123461844907311&w=2), for the > > > work to T.C. Hollingsworth and various GoogleGoogle Code-In 2011 > > > participants. > > > > > > Now we have: > > > > > > * entities from kdelibs/kdoctools/customization/ (help-menu, > > > install-intro, report-bugs, install-compile, update-doc etc) pulled into > > > all application docbooks. > > > Not processed by scripty, so translation teams are not automatically > > > notified about changes/updates > > > * lot of docs for task common to all KDE applications (shortcuts, > > > toolbars, spellcheck, file dialog, common menu items etc) slightly > > > different in many application docbooks. > > > > > > With building blocks: > > > * all common docs in one place > > > * move as much as possible (all?) from kdelibs/kdoctools/customization > > > into building blocks > > > * in application docbooks sections about shortcuts, toolbars, > > > spellcheck, > > > file dialog, common menu items, help menu etc will be replaced with > > > links > > > to the relevant section in building blocks. > > > > > > Benefits with building blocks: > > > > > > * documentation team: > > > one central place to keep the common doc stuff up to date > > > not wasting time to keep similar docs spread over may docbooks up to > > > date, > > > > > > but concentrate on application specific tasks and infos > > > > > > * translation teams: > > > automatical notification via scripty about changes of entities now in > > > > > > kdelibs only one translation of common tasks, not many but slightly > > > different in several application docbooks > > > > > > * users > > > > > > experienced kde user are not bored reading known infos over and and > > > over again in any docbook, they get only the application specific > > > infos > > > > > > Migration procedure: > > > > > > Copy of finished parts of buildingblocks should go into master > > > immediately and should be backported to 4.8 as usual. Chapter/Section > > > with info about getting the sources and build it has to be added asap, > > > because in ~50 % of all application docbooks it is currently wrong due > > > to splitted git repos (e. g. no kdeedu tarball any more) > > > > > > In the meantime the doc team tries to improve and extend the building > > > blocks in branches/work (visuell dictionary, a11y, application overview > > > for common tasks, etc, etc) and copy to master/backport the parts ready > > > to get in. > > > > > > For translation teams the building blocks in stable should be kind of > > > essential like the essentials for GUI. > > > > > > If we have enough (what is enough here?) translated building blocks in > > > stable, the doc team can start to replace every info in an application > > > docbook which is in building blocks with a link. Of course first only in > > > kde main modules, later on in extragear + playground. > > > > > > Both systems have to coexist for at least a few years until all > > > applications in kde git require a minimum kde version with the building > > > blocks. > > > > _______________________________________________ > > kde-doc-english mailing list > > kde-doc-english at kde.org > > https://mail.kde.org/mailman/listinfo/kde-doc-english