Am 05.01.2015 um 10:01 schrieb John Hewson <j...@jahewson.com>: > > >> On 4 Jan 2015, at 13:40, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >> >> Hi >> >> Am 04.01.2015 um 22:24 schrieb John Hewson <j...@jahewson.com>: >> >>> >>> >>>> On 4 Jan 2015, at 13:18, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>>> >>>> Hi John, >>>> >>>> >>>> Am 04.01.2015 um 22:05 schrieb John Hewson <j...@jahewson.com >>>> <mailto:j...@jahewson.com>>: >>>> >>>>> >>>>>> On 4 Jan 2015, at 11:35, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>>>>> >>>>>> >>>>>>> P.S. I managed to publish a small change as a test, using the web-based >>>>>>> CMS. But I’d like to understand (and document?) the complete template >>>>>>> and build setup. >>>>>>> >>>>>> >>>>>> Great. >>>>>> >>>>>> WRT the documentation. There is nothing special on our setup i.e. we are >>>>>> using the 'regular' Apache CMS build system. So the documentation at >>>>>> http://www.apache.org/dev/cmsref.html applies. >>>>>> >>>>>> To give you a quick overview: >>>>>> >>>>>> Everytime there is a change to the svn source tree a build is triggered: >>>>>> >>>>>> - looking at lib/path.pm to match the entries in content against the >>>>>> expressions in path.pm. First match wins. >>>>>> - from path.pm selecting the view in lib/view.pm >>>>>> - from view.pm selecting the template in templates/ >>>>>> - the templates consisting of the html source with django template >>>>>> expression for logic >>>>>> [https://docs.djangoproject.com/en/1.7/topics/templates/] >>>>>> >>>>>> Is there something specific you are looking for? >>>>> >>>>> I’m trying to understand how our JavaDoc gets published, and how the new >>>>> docs on git will be published in the future. >>>> >>>> JavaDoc: that's currently a manual process. I'm creating the directory, >>>> and upload a tarball -> >>>> http://www.apache.org/dev/cmsref.html#generated-docs >>>> <http://www.apache.org/dev/cmsref.html#generated-docs> >>>> git docs: we are not there yet - basically you can reference svn and git >>>> repositories from within the Apache CMS. Unfortunately this is not well >>>> documented. The documentation for that feature refers to the Apache Thrift >>>> project which is using that. See the discussion about the feature >>>> implementation. >>>> http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms >>>> <http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms> >>> >>> Ok, thanks, I think I have all I need for now. Getting the git integration >>> working should be a priority as I’m reluctant to start writing docs in git >>> if it may never get up and running. >>> >> >> If you want to do the writeup now I'd suggest that you add the content in >> SVN as I can guarantee a certain date until that will be available. As I >> wrote the documentation over and above the basics is very poor and one needs >> to inspect the sources of other projects. > > Ok, I’ll add content to SVN. I want to at least rework the existing 1.8 > content to apply to 2.0 and add some notes on migration from 1.8 to 2.0. > >> If you don't mind it would be good to have the following pattern for the >> content >> >> - sections which holds user centric content (e.g. Rendering might be more >> meaningful than PDModel) >> - if there are multiple entries in a section a README.md and/or index.md as >> this will play well with GitHub with an overview of the section and relative >> links to the subentries as needed. > > Sounds good. > >>> I’m going to try to move the 1.8 information which is scattered around or >>> website under a common section, so that we can add a 2.0/trunk section soon >>> and begin getting docs ready. >> >> My plan was to have all documentation under a common section and a version >> switch. This way we could reuse that if there is a 2.1 …. - I trust you have >> your own ideas. > > Yes, we will need both sets of docs to be available. I’ve looked at a few > different Apache projects and Tika provides what I consider to be the ideal > solution http://tika.apache.org/ <http://tika.apache.org/> with all > version-specific docs pages in a per-version subtree in their sidebar. >
good example. My thoughts were to a) have the navigation on top to get some extra space b) add the documentation similar to http://cordova.apache.org/docs/en/4.0.0/ if you select Documentation in the navigation with a documentation related sidebar for the content c) move all documentation related content into there including Dependencies, Building PDFBox and FAQ. d) rename the section 'For Developers' to 'For Contributors' e) document some of the contribution for the website in there f) add at least the JavaDocs for fontbox, xmpbox and preflight Maybe we do that first and then concentrate on getting the release ready (I still have a lot to do on the AcroForms stuff) and get the pdfbox-docs integration done afterwards. If there are tasks I can help you with just let me know. WDYT? Maruan >> BR >> >> Maruan >> >>> >>>> BR >>>> Maruan >>>> >>>> >>>>> >>>>>> BR >>>>>> >>>>>> Maruan >>>>>> >>>>>>> -- John >>>>>>> >>>>>>>> On 3 Jan 2015, at 16:59, John Hewson <j...@jahewson.com> wrote: >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>>> On 2 Jan 2015, at 22:47, Maruan Sahyoun <sahy...@fileaffairs.de> >>>>>>>>> wrote: >>>>>>>>> >>>>>>>>> Am 03.01.2015 um 04:21 schrieb John Hewson <j...@jahewson.com>: >>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>>> On 2 Jan 2015, at 16:25, Maruan Sahyoun <sahy...@fileaffairs.de> >>>>>>>>>>> wrote: >>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>>> On 1 Jan 2015, at 22:23, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>>>>>>>>>>> >>>>>>>>>>>>> Hi John, >>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>>>>> On 1 Jan 2015, at 14:40, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de> <mailto:sahy...@fileaffairs.de >>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de>>> wrote: >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> This isn’t a good situation at all, we had a usable >>>>>>>>>>>>>>>> documentation system in October and now we have nothing >>>>>>>>>>>>>>>> usable, with almost no content and no way to easily contribute. >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> how is the content different from the existing one? There >>>>>>>>>>>>>>> wasn't a lot of content and there still isn't. That usable >>>>>>>>>>>>>>> documentation system wasn't used a lot. >>>>>>>>>>>>>> >>>>>>>>>>>>>> Most of the website is missing, all we have is the cookbook. >>>>>>>>>>>>>> There’s no way to build, deploy or preview anything. >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> it's not meant to replace the whole website. That will still >>>>>>>>>>>>> reside in the Apache CMS which will pull the docs sources from >>>>>>>>>>>>> GitHub (I explained that in a ticket). >>>>>>>>>>>> >>>>>>>>>>>> Do you mean PDFBOX-2340? I assumed that “pdfbox docs” meant our >>>>>>>>>>>> entire website. I guess not. So this means we have some of the >>>>>>>>>>>> website on SVN and some of it on Git? And no single revision >>>>>>>>>>>> number for the overall site? >>>>>>>>>>> >>>>>>>>>>> The discussion before pdfbox-docs has been created was to have the >>>>>>>>>>> documentation on git not the overall website. The build system ist >>>>>>>>>>> still the Apache CMS as is currently in use. That will have the >>>>>>>>>>> templates, the build scripts …. - as is today. >>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>>> pdfbox-docs will hold the sources for the documentation. I >>>>>>>>>>>>> brought the cookbook entries so one can see some of the structure. >>>>>>>>>>>> >>>>>>>>>>>> What about the other existing docs? How do I contribute to those? >>>>>>>>>>>> On SVN? >>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> We’d agreed that moving to docs to GitHub was an experiment to >>>>>>>>>>>>>>>> see if it made contributing easier but it’s had the opposite >>>>>>>>>>>>>>>> effect, we’re in a less usable state than ever. It seems like >>>>>>>>>>>>>>>> we’d be better off going back to our working SVN documentation >>>>>>>>>>>>>>>> and creating a new 2.0 branch from the 1.8 docs and then >>>>>>>>>>>>>>>> updating them. We just haven’t realised the benefit from doing >>>>>>>>>>>>>>>> things differently. >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> There were no major contributions to the documentation using >>>>>>>>>>>>>>> SVN. Everybody could have done it before but didn't. The non >>>>>>>>>>>>>>> existing content is not because of GitHub (or SVN). >>>>>>>>>>>>>> >>>>>>>>>>>>>> If there’s no advantage to using GitHub then we probably >>>>>>>>>>>>>> shouldn’t use it. This was a test to see if there were benefits… >>>>>>>>>>>>>> but there seem to be none. >>>>>>>>>>>>>> >>>>>>>>>>>>>>> So my suggestion is to put the content you are planning to >>>>>>>>>>>>>>> contribute into pdfbox-docs. Now if you put it into the CMS >>>>>>>>>>>>>>> fine. We can later make it available in pdfbox-docs. >>>>>>>>>>>>>> >>>>>>>>>>>>>> I’d like to do that, but unless I need to be able to build and >>>>>>>>>>>>>> deploy the docs to the website somehow. >>>>>>>>>>>>>> >>>>>>>>>>>>>>> I take some of the blame as I didn't find the time to >>>>>>>>>>>>>>> enhance/restructure the website - again that's not GitHubs >>>>>>>>>>>>>>> fault. >>>>>>>>>>>>>> >>>>>>>>>>>>>> Enhancements are of course welcome, but we need the old >>>>>>>>>>>>>> functionality working, at a bare minimum. e.g. where has most of >>>>>>>>>>>>>> the website gone? >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> the restructuring is necessary because the pull mechanism needs >>>>>>>>>>>>> to be enabled. >>>>>>>>>>>>> >>>>>>>>>>>>> In addition there needs to be the place for the PDFBox 2 docs >>>>>>>>>>>>> together with the old 1.8 docs. That's independent from using SVN >>>>>>>>>>>>> or GitHub. >>>>>>>>>>>> >>>>>>>>>>>> All we need is a branch in SVN. There’s no need to put the 1.8 >>>>>>>>>>>> docs on GitHub, they’re going to obsolete in a few months. The >>>>>>>>>>>> simplest possible solution is to just create a new 2.0 docs branch >>>>>>>>>>>> on SVN. >>>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> That's revisiting the git/svn discussion. If there is agreement >>>>>>>>>>> that it shall stay on SVN fine. >>>>>>>>>>> >>>>>>>>>>>>> I have a little more time now so can look into that (and put the >>>>>>>>>>>>> AcroForm stuff to the side for the moment). OTOH if you or >>>>>>>>>>>>> someone else wants to do it let me know. >>>>>>>>>>>> >>>>>>>>>>>> I’m a little stuck to be honest, it seems that our documentation >>>>>>>>>>>> system is currently non-functional and part of it is on git for no >>>>>>>>>>>> clear reason… >>>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> We had the git discussion before pdfbox-docs has been created. If >>>>>>>>>>> we want to revisit that we can always do. >>>>>>>>>>> >>>>>>>>>>> Other than that there is a functional documentation system. You can >>>>>>>>>>> add to the documentation today using svn only or together with >>>>>>>>>>> pdfbox-docs, do a local build for testing and submit your changes. >>>>>>>>>> >>>>>>>>>> What is the workflow for updating pdfbox-docs and pushing it to the >>>>>>>>>> website? If I make a change to pdfbox-docs what else do I have to do >>>>>>>>>> to get that published on the website? >>>>>>>>> >>>>>>>>> Assuming that the templates, references, scripts are in place you'd >>>>>>>>> have to trigger the Apache CMS build which will regenerate the >>>>>>>>> website (pulling the pdfbox-docs sources) and publish it to the >>>>>>>>> staging website. From there you'd have to publish to the production >>>>>>>>> website. The Apache CMS always builds to staging. >>>>>>>>> >>>>>>>>> You could also use an external build system for the pdfbox-docs files >>>>>>>>> and from there push the files to the Apache CMS svn tree or upload a >>>>>>>>> compressed archive. Again this will trigger a build to staging. >>>>>>>>> Uploading an archive is how we publish the PDFBox javadoc files. >>>>>>>>> >>>>>>>>> If you'd like to update production directly you need to build >>>>>>>>> independently from the Apache CMS and push to the production tree. >>>>>>>>> There needs to be a configuration file (extpaths.txt) in the Apache >>>>>>>>> CMS which will tell the Apache CMS to not overwrite that part of the >>>>>>>>> tree. >>>>>>>>> >>>>>>>>> A more complete description of the possibilities is in >>>>>>>>> http://www.apache.org/dev/cmsref.html#external-build. >>>>>>>> >>>>>>>> There seem to be a lot of options and customisations possible with the >>>>>>>> Apache CMS. Do we have a step-by-step workflow documented anywhere >>>>>>>> specifically describing how the pdfbox website is currently being >>>>>>>> managed? >>>>>>>> >>>>>>>>>> >>>>>>>>>>> Now there is no sample doing it this way in the PDFBox CMS sources >>>>>>>>>>> as I didn't have the time yet to create one. The Apache CMS >>>>>>>>>>> capabilities are documented at >>>>>>>>>>> http://www.apache.org/dev/cmsref.html >>>>>>>>>>> <http://www.apache.org/dev/cmsref.html>. Some of the more advanced >>>>>>>>>>> capabilities are not well documented but need to be gathered by >>>>>>>>>>> inspecting the code or looking at other projects using the Apache >>>>>>>>>>> CMS. >>>>>>>>>>> >>>>>>>>>>> BTW no need to wait for me doing these changes as every committer >>>>>>>>>>> has access. >>>>>>>>>>> >>>>>>>>>>> BR >>>>>>>>>>> Maruan >>>>>>>>>>> >>>>>>>>>>>>> BR - Maruan >>>>>>>>>>>>> >>>>>>>>>>>>>>> Maruan >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> -- John >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> On 1 Jan 2015, at 12:52, Maruan Sahyoun >>>>>>>>>>>>>>>>> <sahy...@fileaffairs.de> wrote: >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> the docs shall reside in pdfbox-docs from where they will be >>>>>>>>>>>>>>>>> pulled onto the website or looked at directly at github. >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> The publishing process to our website is not yet in place as >>>>>>>>>>>>>>>>> there is no new content. I'm looking to get the redesign of >>>>>>>>>>>>>>>>> the website done to accommodate for the old 1.8 and new 2.0 >>>>>>>>>>>>>>>>> release. >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> Maruan >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> Am 01.01.2015 um 19:38 schrieb John Hewson >>>>>>>>>>>>>>>>> <j...@jahewson.com>: >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> Hi All, >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> We’re getting closer to 2.0 being ready and I’m thinking >>>>>>>>>>>>>>>>>> about writing some docs, but currently the situation seems >>>>>>>>>>>>>>>>>> to be worse than it was before the docs stated moving to >>>>>>>>>>>>>>>>>> GitHub - where are our canonical docs and how can I >>>>>>>>>>>>>>>>>> contribute to them? >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> All I see on GitHub is some old 1.8 stuff and an incomplete >>>>>>>>>>>>>>>>>> cookbook for forms. Is this content live anywhere? Is there >>>>>>>>>>>>>>>>>> a pay to preview it? >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> -- John >>> >> >
